> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.fax.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# List fax records

> Get your own or your subordinate's faxes list. (Permitted scopes: **fax:all:read**, **fax:fax:read**)

<RequestExample>
  ```js NodeJS SDK theme={null}
  const axios = require('axios');
  const FaxesApiFp = require('@alohi/faxplus-api').FaxesApiFp;
  const Configuration = require('@alohi/faxplus-api').Configuration;

  const config = new Configuration({
      accessToken: accessToken,
      basePath: 'https://restapi.fax.plus/v3',
      // Header required only when using the OAuth2 token scheme
      baseOptions: {
          headers: {
            "x-fax-clientid": clientId,
          }
      }
  });

  async function listFaxes() {
      const reqParams = {
          "userId": '13d8z73c',
          "category": 'inbox',
          "after": '2018-01-01 00:00:00',
          "before": '2020-01-01 00:00:00',
          "limit": '50'
      }
      const req = await FaxesApiFp(config).listFaxes(reqParams);
      const resp = await req(axios);
  }

  listFaxes()
  ```

  ```python Python SDK theme={null}
  from faxplus import ApiClient, FaxesApi
  from faxplus.configuration import Configuration

  conf = Configuration()
  conf.access_token = access_token
  # header_name and header_value required only when using the OAuth2 token scheme
  api_client = ApiClient(header_name='x-fax-clientid', header_value=client_id, configuration=conf)
  api = FaxesApi(api_client)
  resp = api.list_faxes(
      user_id='13d8z73c',
      category='inbox',
      after='2018-01-01 00:00:00',
      before='2020-01-01 00:00:00',
      limit='50')
  ```

  ```java Java theme={null}
  /**
   * Example below uses Apache HTTP Client 4 with Fluent API
   **/

  Map<String, String> pathParams = new HashMap<>();
  pathParams.put("user_id", "'13d8z73c'");

  StrSubstitutor sub = new StrSubstitutor(values, "{", "}");
  String url = sub.replace("https://restapi.fax.plus/v3/accounts/{user_id}/faxes");

  String result = Request
      .Get(url)
       // The x-fax-clientid header is required only when using the OAuth2 token scheme
      .addHeader("x-fax-clientid", "YOUR_CLIENT_ID")
      .addHeader("Accept", "'application/json'")
      .addHeader("Authorization", "'Bearer {access-token}'")
      .execute()
      .returnContent().asString();

  System.out.println(result.toString());
  ```

  ```go Go theme={null}
  package main

  import (
         "bytes"
         "net/http"
  )

  func main() {

      headers := map[string][]string{
          // The x-fax-clientid header is required only when using the OAuth2 token scheme
          "Accept": []string{"application/json"},
          "Authorization": []string{"Bearer {access-token}"},
          "x-fax-clientid": []string{"YOUR_CLIENT_ID"}
      }

      data := bytes.NewBuffer([]byte{jsonReq})
      req, err := http.NewRequest("GET", "https://restapi.fax.plus/v3/accounts/{user_id}/faxes", data)
      req.Header = headers

      client := &http.Client{}
      resp, err := client.Do(req)
      // ...
  }
  ```

  ```php PHP theme={null}
  <?php

  require 'vendor/autoload.php';

  $headers = array(
      'Accept' => 'application/json',
      'Authorization' => 'Bearer {access-token}',
      // The x-fax-clientid header is required only when using the OAuth2 token scheme
      'x-fax-clientid' => '{client ID}',
  );

  $client = new GuzzleHttp\Client();

  try {
      $response = $client->request('GET','https://restapi.fax.plus/v3/accounts/{user_id}/faxes', array(
          'headers' => $headers,
          )
      );
      print_r($response->getBody()->getContents());
   }
   catch (GuzzleHttp\Exception\BadResponseException $e) {
      // handle exception or api errors.
      print_r($e->getMessage());
   }

   // ...
  ```

  ```bash cURL theme={null}
  # You can also use wget
  curl -X GET https://restapi.fax.plus/v3/accounts/{user_id}/faxes \
    -H 'Accept: application/json'  \
    -H 'Authorization: Bearer {access-token}' \
    # The x-fax-clientid header is required only when using the OAuth2 token scheme
    -H 'x-fax-clientid: "YOUR CLIENT_ID"'
  ```
</RequestExample>


## OpenAPI

````yaml get /accounts/{user_id}/faxes
openapi: 3.0.1
info:
  title: Fax.Plus REST API
  description: >-
    This is the Fax.Plus API v3 developed for third party developers and
    organizations. In order to have a better coding experience with this API,
    let's quickly go through some points:<br /><br /> - This API assumes
    **/accounts** as an entry point with the base url of
    **https://restapi.fax.plus/v3**. <br /><br /> - This API treats all date and
    times sent to it in requests as **UTC**. Also, all dates and times returned
    in responses are in **UTC**<br /><br /> - Once you have an access_token, you
    can easily send a request to the resource server with the base url of
    **https://restapi.fax.plus/v3** to access your permitted resources. As an
    example to get the user's profile info you would send a request to
    **https://restapi.fax.plus/v3/accounts/self** when **Authorization** header
    is set to **Bearer YOUR_ACCESS_TOKEN** and custom header of
    **x-fax-clientid** is set to YOUR_CLIENT_ID
  version: 3.4.0
  contact:
    name: Fax.Plus
    email: info@fax.plus
    url: https://github.com/alohi
servers:
  - url: https://restapi.fax.plus/v3
  - url: /v3
security: []
paths:
  /accounts/{user_id}/faxes:
    get:
      tags:
        - Faxes
      summary: List fax records
      description: >-
        Get your own or your subordinate's faxes list. (Permitted scopes:
        **fax:all:read**, **fax:fax:read**)
      operationId: listFaxes
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            default: self
          description: >-
            User ID. Use 'self' for your own account, or provide a specific user
            ID for corporate member accounts.
          example: self
        - in: query
          name: category
          schema:
            type: string
            enum:
              - inbox
              - sent
              - spam
            default: inbox
          required: false
          description: >-
            Category parameter. Valid string values: **inbox** (received faxes),
            **sent** (outgoing faxes), or **spam** (spam faxes). Optional,
            defaults to 'inbox'.
          example: inbox
        - in: query
          name: after
          schema:
            type: string
            pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}
          required: false
          description: >-
            Start date to get records from that date. Format: *YYYY-MM-DD
            HH:mm:ss* (e.g., '2018-01-01 00:00:00'). Optional, if omitted
            returns all records from the beginning.
          example: '2018-01-01 00:00:00'
        - in: query
          name: before
          schema:
            type: string
            pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2}
          required: false
          description: >-
            End date to get records before that date. Format: *YYYY-MM-DD
            HH:mm:ss* (e.g., '2020-01-01 00:00:00'). Optional, if omitted
            returns all records up to the current time.
          example: '2020-01-01 00:00:00'
        - in: query
          name: limit
          schema:
            type: integer
            maximum: 50
            minimum: 1
            default: 50
          required: false
          description: >-
            Maximum number of fax records to return per request. Must be between
            1 and 50. Optional, defaults to 50. Use with 'offset' for
            pagination.
          example: 50
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 0
            maximum: 2147483647
            default: 0
          required: false
          description: >-
            Offset for pagination. Specifies the number of records to skip
            before starting to return records. Optional, defaults to 0.
          example: 0
        - in: query
          name: sort_by
          schema:
            type: string
            enum:
              - date
              - from
              - to
              - comment
              - pages
          required: false
          description: >-
            Field to sort the results by. Valid values: **date**, **from**,
            **to**, **comment**, **pages**. Optional.
          example: date
        - in: query
          name: order
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
          required: false
          description: >-
            Order of the sorting. Valid values: **asc** for ascending, **desc**
            for descending. Optional, defaults to 'asc'.
          example: asc
        - in: query
          name: in_progress
          schema:
            type: boolean
            default: false
          required: false
          description: >-
            Return in-progress incoming faxes. Optional, defaults to false. This
            functionality can be enabled on request.
          example: true
        - in: query
          name: status
          schema:
            type: array
            items:
              $ref: '#/components/schemas/FaxStatus'
          style: form
          explode: false
          required: false
          description: >-
            Filter by transmission status. Comma-separated list of valid fax
            statuses
          example:
            - success
            - partially_received
        - in: query
          name: from_number
          schema:
            type: string
            pattern: ^[+][1-9][0-9]{1,14}$
            minLength: 2
            maxLength: 16
          required: false
          description: Filter by source/from fax number in E.164 format
          example: '+12025551234'
        - in: query
          name: to_number
          schema:
            type: string
            pattern: ^[+][1-9][0-9]{1,14}$
            minLength: 2
            maxLength: 16
          required: false
          description: Filter by destination/to fax number in E.164 format
          example: '+19876543210'
        - in: query
          name: is_read
          schema:
            type: boolean
          required: false
          description: >-
            Filter by read status. **true** for read faxes, **false** for unread
            faxes
          example: false
        - in: query
          name: min_pages
          schema:
            type: integer
            minimum: 0
            maximum: 9999
          required: false
          description: Filter faxes with at least this many pages
          example: 1
        - in: query
          name: max_pages
          schema:
            type: integer
            minimum: 0
            maximum: 9999
          required: false
          description: Filter faxes with at most this many pages
          example: 10
      responses:
        '200':
          $ref: '#/components/responses/FaxList'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - oauth2:
            - all
        - personal_access_token:
            - fax:all:read
            - fax:fax:read
components:
  schemas:
    FaxStatus:
      description: >-
        Fax status. Some failure codes use failed_fs_* values which represent
        low-level fax transport issues (for example, fax protocol
        incompatibility, the remote endpoint stopping responding, or remote
        disconnections). In particular: failed_fs_8/failed_fs_9 indicate
        protocol incompatibility; failed_fs_31/failed_fs_32 indicate that the
        remote stopped responding; failed_fs_35/failed_fs_39 indicate that the
        remote disconnected.
      enum:
        - success
        - partially_sent
        - partially_received
        - in_progress
        - insufficient_credit
        - failed
        - failed_internal_process_error
        - failed_user_busy
        - failed_no_answer
        - failed_unallocated_number
        - failed_office_converter_issue
        - failed_separate_file_pages_issue
        - failed_render_header_issue
        - failed_invalid_number_format
        - failed_mimetype_not_supported
        - failed_destination_not_supported
        - failed_image_preparation
        - failed_to_send
        - failed_normal_temporary_failure
        - failed_unknown_converter_issue
        - failed_normal_clearing
        - failed_convert_to_tiff_issue
        - failed_fs_2
        - failed_fs_3
        - failed_fs_8
        - failed_fs_9
        - failed_fs_31
        - failed_fs_32
        - failed_fs_35
        - failed_fs_39
        - failed_fs_48
        - failed_fs_49
      type: string
    FaxList:
      description: List of fax data
      properties:
        data:
          $ref: '#/components/schemas/FaxListData'
      type: object
      additionalProperties: false
    Error:
      properties:
        description:
          type: string
        error:
          type: string
      additionalProperties: false
    FaxListData:
      properties:
        records:
          items:
            $ref: '#/components/schemas/Fax'
          type: array
      type: object
      additionalProperties: false
    Fax:
      type: object
      example:
        comment: ''
        cost: 2
        cost_details:
          multiplier: 1
          notification_cost: 0
        description: OK
        direction: incoming
        duration: 0
        file: ec28edc283a74daca1787efb5fa6fae2.tiff
        file_name: fax-from-12076001783
        from_number: '+12076001783'
        header: null
        id: 5e7de3ad54cfd54eb568cc76
        is_read: false
        is_spam: false
        last_update: '2020-03-27 11:29:49'
        max_retry: null
        owner_id: 74d59d2779fb42a99cd5bb993c0c89d2
        pages: 2
        retry_delay: null
        scheduled_time: null
        start_time: '2020-03-27 11:29:21'
        status: failed
        submit_time: null
        to: '+12076001783'
      properties:
        comment:
          description: Free-form comment
          type: string
        cost:
          description: Fax cost in the user currency
          type: integer
          minimum: 0
        cost_details:
          properties:
            multiplier:
              type: number
              minimum: 0
            notification_cost:
              type: number
              minimum: 0
          type: object
        description:
          type: string
        direction:
          $ref: '#/components/schemas/FaxDirection'
        duration:
          type: integer
          minimum: 0
          description: Fax transmission duration in seconds
        file:
          description: Fax file ID for the getFile handle
          type: string
        file_name:
          description: Human-readable file name
          type: string
        from:
          description: >-
            Sender number. Might be a userId for faxes sent or received with
            free accounts
          type: string
        header:
          type: string
        id:
          description: Fax ID
          type: string
        is_read:
          type: boolean
        is_spam:
          description: True if the fax is marked as spam
          type: boolean
        last_update:
          type: string
        max_retry:
          description: Maximum number of retries
          maximum: 3
          minimum: 0
          type: integer
        owner_id:
          description: User ID of the fax owner
          type: string
        pages:
          description: Number of pages in the fax
          minimum: 0
          type: integer
        retry_delay:
          description: Delay between two retries
          maximum: 180
          minimum: 0
          type: integer
        scheduled_time:
          type: string
        start_time:
          description: 'Time at which faxing session started. Format: YYYY-MM-DD HH:mm:ss'
          type: string
        status:
          $ref: '#/components/schemas/FaxStatus'
        submit_time:
          description: Time when the fax was submitted for sending. For outgoing faxes only
          type: string
        to:
          description: >-
            Fax destination number. Might be a userId for faxes sent or received
            with free accounts
          type: string
        cover_page:
          $ref: '#/components/schemas/FaxCoverPage'
      required:
        - id
        - owner_id
        - status
        - pages
        - comment
        - cost_details
      additionalProperties: false
    FaxDirection:
      description: Fax direction
      enum:
        - outgoing
        - incoming
      type: string
    FaxCoverPage:
      description: Fax cover page
      type: object
      required:
        - name_to
        - name_from
        - subject
      properties:
        name_to:
          type: string
          description: TO field on the cover page
        name_from:
          type: string
          description: FROM field on the cover page
        subject:
          type: string
          description: SUBJECT field on the cover page
        flags:
          type: array
          description: Cover page flags
          items:
            $ref: '#/components/schemas/CoverPageFlags'
        message:
          type: string
          description: MESSAGE field on the cover page
        include_company_logo:
          type: boolean
          description: Whether to include the company logo on the cover page
    CoverPageFlags:
      description: Allowed flags for the cover page
      type: string
      enum:
        - urgent
        - for_review
        - please_reply
        - confidential
  responses:
    FaxList:
      description: Response containing a list of faxes
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FaxList'
    Error:
      description: Error object in case there's a problem with given data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_user_id
            description: Invalid user id given
    UnauthorizedError:
      description: Error object in case there's a problem with the authorization
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            description: >-
              The access token provided is expired, revoked, malformed, or
              invalid for other reasons.
    ServerError:
      description: Error object in case there's a server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal_server_error
            description: An unexpected error happened, please contact support
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 Authorization Grant
      flows:
        authorizationCode:
          authorizationUrl: >-
            https://accounts.fax.plus/login?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=all
          tokenUrl: https://accounts.fax.plus/token
          refreshUrl: >-
            https://accounts.fax.plus/token?grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN
          scopes:
            all: >-
              for now when a user grants permission, all grants will be
              permitted
    personal_access_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Personal Access Token (PAT) is a Bearer token used for secure API calls.
        For direct API calls, the PAT is used in the Authorization header as
        'Bearer {PAT}'. For MCP usage, configure your PAT in your MCP client
        settings (e.g., in your IDE's MCP server configuration) - authentication
        will be handled automatically.

````