---
openapi: 3.0.0
info:
  version: "1.0.1"
  title: Call Recording API
  description: |
    The Vonage Business Cloud Call Recording API enables you to manage your company and on-demand call recordings.

    Your application must subscribe to the CallRecording API suite to use this API.
  contact:
    name: "Vonage Business Cloud Support"
    url: "https://businesssupport.vonage.com/contactus"
  termsOfService: "https://www.vonage.com/business/legal-policy-center/business-cloud/tos"
tags:
  - name: Company Call Recording
    description: "Company Call Recording lets administrators schedule call recording rules and recording parameters for your entire office."
  - name: On-Demand Call Recording
    description: "On-Demand Call Recording lets employees decide when to record calls. It’s a particularly useful phone recording system for businesses when you need to verify the details of a conversation or when it’s essential that you capture accurate notes"
  - name: Export Job
    description: "Export jobs let users download recordings in bulk based on search criteria. Export jobs are initiated from the corresponding company and on-demand call recording export endpoints."
paths:
  "/api/accounts/{account_id}/company_call_recordings":
    get:
      operationId: getCCRecordings
      summary: Get company call recordings
      description: Get company call recordings for an account
      tags:
        - company call recording
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/CallDirection"
        - $ref: "#/components/parameters/CallID"
        - $ref: "#/components/parameters/CallerID"
        - $ref: "#/components/parameters/Cnam"
        - $ref: "#/components/parameters/Dnis"
        - $ref: "#/components/parameters/DurationGte"
        - $ref: "#/components/parameters/DurationLte"
        - $ref: "#/components/parameters/Extension"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/StartGte"
        - $ref: "#/components/parameters/StartLte"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompanyCallRecordingsHalResponse"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
  "/api/accounts/{account_id}/company_call_recordings/{recording_id}":
    get:
      operationId: getCCRecording
      summary: Get single company call recording
      description: Get a single company call recording for an account
      tags:
        - company call recording
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/RecordingID"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompanyCallRecordingHalResponse"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
    delete:
      operationId: deleteCCRecording
      summary: Delete company call recording
      description: Delete a single company call recording for an account
      tags:
        - company call recording
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/RecordingID"
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
  "/api/accounts/{account_id}/company_call_recordings/export":
    post:
      operationId: createCCRExportJob
      summary: Create a company call recording export job
      description: Create a company call recording export job for an account
      tags:
        - company call recording
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Filters"
      responses:
        "202":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateExportJobHalResponse"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
  "/api/accounts/{account_id}/users/{user_id}/call_recordings":
    get:
      operationId: getODCRecordings
      summary: Get on-demand call recordings
      description: Get on-demand call recordings for an account user
      tags:
        - on-demand call recording
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/UserID"
        - $ref: "#/components/parameters/CallDirection"
        - $ref: "#/components/parameters/CallID"
        - $ref: "#/components/parameters/CallerID"
        - $ref: "#/components/parameters/Cnam"
        - $ref: "#/components/parameters/Dnis"
        - $ref: "#/components/parameters/DurationGte"
        - $ref: "#/components/parameters/DurationLte"
        - $ref: "#/components/parameters/Extension"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PageSize"
        - $ref: "#/components/parameters/StartGte"
        - $ref: "#/components/parameters/StartLte"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OnDemandCallRecordingsHalResponse"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
  "/api/accounts/{account_id}/users/{user_id}/call_recordings/{recording_id}":
    get:
      operationId: getODCRecording
      summary: Get single on-demand call recording
      description: Get a single on-demand call recording for an account user
      tags:
        - on-demand call recording
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/UserID"
        - $ref: "#/components/parameters/RecordingID"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OnDemandCallRecordingHalResponse"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
    delete:
      operationId: deleteODCRecording
      summary: Delete on-demand call recording
      description: Delete a single on-demand call recording for an account user
      tags:
        - on-demand call recording
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/UserID"
        - $ref: "#/components/parameters/RecordingID"
      responses:
        "204":
          description: No Content
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
  "/api/accounts/{account_id}/users/{user_id}/call_recordings/export":
    post:
      operationId: createODCRExportJob
      summary: Create an on-demand call recording export job
      description: Create an on-demand call recording export job for an account user
      tags:
        - on-demand call recording
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/UserID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Filters"
      responses:
        "202":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateExportJobHalResponse"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
  "/api/accounts/{account_id}/users/{user_id}/call_recordings/jobs":
    get:
      operationId: getCCRExportJobs
      summary: Get call recording export jobs
      description: Get call recording export jobs for an account user
      tags:
        - export job
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/UserID"
        - $ref: "#/components/parameters/Status"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportJobsHalResponse"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
  "/api/accounts/{account_id}/users/{user_id}/call_recordings/jobs/{job_id}":
    get:
      operationId: getCCRExportJob
      summary: Get call recording export job
      description: Get a single call recording export job for an account user
      tags:
        - export job
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/AccountID"
        - $ref: "#/components/parameters/UserID"
        - $ref: "#/components/parameters/JobID"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExportJobHalResponse"
        "401":
          description: Unauthorized
        "403":
          description: Forbidden
        "404":
          description: Not Found
servers:
  - url: https://api.vonage.com/t/vbc.prod/call_recording
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth

  parameters:
    AccountID:
      name: account_id
      in: path
      required: true
      schema:
        type: string
      description: The Vonage Business Cloud account ID. You can use 'self' to refer to the authenticated user's account.
      example: 549825
    UserID:
      name: user_id
      in: path
      description: The Vonage Business Cloud user ID. You can use 'self' to refer to the authenticated user.
      required: true
      example: 745249
      schema:
        type: string
    JobID:
      name: job_id
      in: path
      description: The job ID
      required: true
      example: 7a688e12-99ee-4816-8385-b21b90583838
      schema:
        type: string
    RecordingID:
      name: recording_id
      in: path
      description: The recording ID
      required: true
      example: 193228
      schema:
        type: string
    Extension:
      name: extension
      in: query
      description: Filter recordings by extension number
      required: false
      example: 999
      schema:
        type: string
    StartLte:
      name: start:lte
      in: query
      description: Filter recordings by start date (less than or equal to)
      example: "2019-01-01T00:00:00+0000"
      required: false
      schema:
        type: string
    StartGte:
      name: start:gte
      in: query
      description: Filter recordings by start date (greater than or equal to)
      example: "2019-01-01T00:00:00+0000"
      required: false
      schema:
        type: string
    CallDirection:
      name: call_direction
      in: query
      description: Filter recordings by call direction
      example: INBOUND
      required: false
      schema:
        type: string
        enum:
          - INBOUND
          - OUTBOUND
          - INTRA_PBX
    CallerID:
      name: caller_id
      in: query
      description: Filter recordings by Caller ID
      example: 17325550100
      required: false
      schema:
        type: string
    CallID:
      name: call_id
      in: query
      description: Filter recordings by Call ID
      example: c91150a6-8cc4-4e73-9fef-17fd925c6448
      required: false
      schema:
        type: string
    Cnam:
      name: cnam
      in: query
      description: Filter recordings by CNAM (Caller ID Name)
      example: 'JOHN SMITH'
      required: false
      schema:
        type: string
    Dnis:
      name: dnis
      in: query
      description: Filter recordings by DNIS (Dialed Number Identification Service)
      example: '17325550100'
      required: false
      schema:
        type: string
    DurationLte:
      name: duration:lte
      in: query
      description: Filter recordings by duration in milliseconds (less than or equal to)
      example: 60000
      required: false
      schema:
        type: integer
    DurationGte:
      name: duration:gte
      in: query
      description: Filter recordings by duration in milliseconds (greater than or equal to)
      example: 60000
      required: false
      schema:
        type: integer
    Status:
      name: status
      in: query
      description: Filter export jobs by status
      required: false
      schema:
        type: string
    Order:
      name: order
      in: query
      description: Sort recordings by field value
      required: false
      schema:
        type: string
        default: start:DESC
      example: start:DESC
    Page:
      name: page
      in: query
      description: Requested page number
      required: false
      schema:
        type: integer
        default: 1
      example: 1
    PageSize:
      name: page_size
      in: query
      description: Requested page size
      required: false
      schema:
        type: integer
        default: 10
      example: 10
  schemas:
    CompanyCallRecording:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the current recording
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/company_call_recordings/193228'
        call_direction:
          type: string
          description: Direction of the recorded call
          example: "INBOUND"
        call_id:
          type: string
          description: Call ID of the recorded call
          example: c91150a6-8cc4-4e73-9fef-17fd925c6448
        caller_id:
          type: string
          description: Caller ID of the caller of the recorded call
          example: 17325550100
        cnam:
          type: string
          description: CNAM (Caller ID Name) of the caller of the recorded call
          example: 'JOHN SMITH'
        dnis:
          type: string
          description: DNIS (Dialed Number Identification Service) of the caller of the recorded call
          example: '17325550100'
        download_url:
          type: string
          description: URL to download the recording. This URL requires authorization with your OAuth token.
          example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/audio/recording/193228'
        duration:
          type: integer
          description: Duration of the recorded call in milliseconds
          example: 60000
        end:
          type: string
          format: date-time
          description: End time of the recorded call
          example: "2019-01-01T00:00:00+0000"
        extensions:
          type: array
          items:
            type: string
          description: Extensions associated with the call recording
          example: [999]
        file_name:
          type: string
          description: File name of the call recording
          example: "730048.11826465111463122315701.95a7584be856e34a582025d420c20d9d.1463122442148.mp3"
        file_size_in_bytes:
          type: integer
          description: File size in bytes of the call recording
          example: 100000
        id:
          type: integer
          description: Unique identifier of the call recording
          example: 193228
        rule_ids:
          type: array
          description: Identifier of the call recording rule(s) that triggered the call recording
          items:
            type: integer
          example: [1989, 2012, 449]
        start:
          type: string
          format: date-time
          description: Start time of the recorded call
          example: "2019-01-01T00:00:00+0000"
    CompanyCallRecordingHalResponse:
      $ref: "#/components/schemas/CompanyCallRecording"
    CompanyCallRecordingsHalResponse:
      type: object
      properties:
        _embedded:
          properties:
            recordings:
              type: array
              items:
                $ref: "#/components/schemas/CompanyCallRecording"
          description: A list of recording objects
        _links:
          type: object
          properties:
            first:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the first page of recordings
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/company_call_recordings?page=0'
            prev:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the previous page of recordings
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/company_call_recordings?page=1'
            self:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the current page of recordings
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/company_call_recordings?page=2'
            next:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the next page of recordings
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/company_call_recordings?page=3'
            last:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the last page of recordings
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/company_call_recordings?page=4'
        page:
          type: integer
        page_size:
          type: integer
        total_items:
          type: integer
        total_pages:
          type: integer
    OnDemandCallRecording:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the current recording
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings/193228'
        call_direction:
          type: string
          description: Direction of the recorded call
          example: "INBOUND"
        call_id:
          type: string
          description: Call ID of the recorded call
          example: c91150a6-8cc4-4e73-9fef-17fd925c6448
        caller_id:
          type: string
          description: Caller ID of the caller of the recorded call
          example: 17325550100
        cnam:
          type: string
          description: CNAM (Caller ID Name) of the caller of the recorded call
          example: 'JOHN SMITH'
        dnis:
          type: string
          description: DNIS (Dialed Number Identification Service) of the caller of the recorded call
          example: '17325550100'
        download_url:
          type: string
          description: URL to download the recording. This URL requires authorization with your OAuth token.
          example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/audio/recording/193228'
        duration:
          type: integer
          description: Duration of the recorded call in milliseconds
          example: 60000
        end:
          type: string
          format: date-time
          description: End time of the recorded call
          example: "2019-01-01T00:00:00+0000"
        extensions:
          type: array
          items:
            type: string
          description: Extensions associated with the call recording
          example: [999]
        file_name:
          type: string
          description: File name of the call recording
          example: "730048.11826465111463122315701.95a7584be856e34a582025d420c20d9d.1463122442148.mp3"
        file_size_in_bytes:
          type: integer
          description: File size in bytes of the call recording
          example: 100000
        id:
          type: integer
          description: Unique identifier of the call recording
          example: 193228
        rule_ids:
          type: array
          description: Identifier of the call recording rule(s) that triggered the call recording
          items:
            type: integer
        start:
          type: string
          format: date-time
          description: Start time of the recorded call
          example: "2019-01-01T00:00:00+0000"
    OnDemandCallRecordingHalResponse:
      $ref: "#/components/schemas/OnDemandCallRecording"
    OnDemandCallRecordingsHalResponse:
      type: object
      properties:
        _embedded:
          properties:
            recordings:
              type: array
              items:
                $ref: "#/components/schemas/CompanyCallRecording"
          description: A list of recording objects
        _links:
          type: object
          properties:
            first:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the first page of recordings
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings?page=0'
            prev:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the previous page of recordings
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings?page=1'
            self:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the current page of recordings
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings?page=2'
            next:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the next page of recordings
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings?page=3'
            last:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the last page of recordings
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings?page=4'
        page:
          type: integer
        page_size:
          type: integer
        total_items:
          type: integer
        total_pages:
          type: integer
    CreateExportJobHalResponse:
      type: object
      properties:
        job_ids:
          type: array
          items:
            type: string
          description: Unique identifier of the created export jobs
          example:
            - afa725fb-d418-4eaf-b3f9-0e66396fafdc
    ExportJob:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the current export job
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings/jobs/5e667ef2-2860-4471-8813-320980a55c20'
        download_url:
          type: string
          description: URL to download the completed export job. This URL requires authorization with your OAuth token.
          example: "https://api.vonage.com/t/vbc.prod/call_recording/api/bulkDownload/retrieve?jobId=afa725fb-d418-4eaf-b3f9-0e66396fafdc"
        files_completed:
          type: integer
          description: Number of files completed by the export job
        files_total:
          type: integer
          description: Number of files included in the export job
          example: 10
        id:
          type: string
          description: Unique identifier of the export job
          example: afa725fb-d418-4eaf-b3f9-0e66396fafdc
        status:
          type: string
          description: Status of the export job
          example: complete
        valid_until:
          type: string
          format: date-time
          description: Expiration time for the complete export job contents
          example: "2019-01-01T00:00:00+0000"
    ExportJobsHalResponse:
      type: object
      properties:
        _embedded:
          properties:
            jobs:
              type: array
              items:
                $ref: "#/components/schemas/ExportJob"
          description: A list of job objects
        _links:
          type: object
          properties:
            first:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the first page of export jobs
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings/jobs?page=0'
            prev:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the previous page of export jobs
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings/jobs?page=1'
            self:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the current page of export jobs
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings/jobs?page=2'
            next:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the next page of export jobs
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings/jobs?page=3'
            last:
              type: object
              properties:
                href:
                  type: string
                  description: URL for the last page of export jobs
                  example: 'https://api.vonage.com/t/vbc.prod/call_recording/api/accounts/549825/users/745249/call_recordings/jobs?page=4'
        page:
          type: integer
        page_size:
          type: integer
        total_items:
          type: integer
        total_pages:
          type: integer
    ExportJobHalResponse:
      $ref: "#/components/schemas/ExportJob"
    Filters:
      type: object
      properties:
        call_direction:
          description: Filter recordings by call direction
          example: INBOUND
          type: string
          enum:
            - INBOUND
            - OUTBOUND
            - INTRA_PBX
        call_id:
          description: Filter recordings by Call ID
          example: c91150a6-8cc4-4e73-9fef-17fd925c6448
          type: string
        caller_id:
          description: Filter recordings by Caller ID
          type: string
          example: 17325550100
        cnam:
          description: Filter recordings by CNAM (Caller ID Name)
          type: string
          example: 'JOHN SMITH'
        dnis:
          description: Filter recordings by DNIS (Dialed Number Identification Service)
          type: string
          example: '17325550100'
        duration:gte:
          description: Filter recordings by duration in milliseconds (greater than or equal to)
          example: 60000
          type: integer
        duration:lte:
          description: Filter recordings by duration in milliseconds (less than or equal to)
          example: 60000
          type: integer
        extension:
          description: Filter recordings by extension number
          example: 999
          type: string
        start:gte:
          description: Filter recordings by start date (greater than or equal to)
          example: "2019-01-01T00:00:00+0000"
          type: string
        start:lte:
          description: Filter recordings by start date (less than or equal to)
          example: "2019-01-01T00:00:00+0000"
          type: string
