openapi: 3.1.0
info:
  version: '3.0'
  title: Fax API
  description: >
    This document provides a detailed user guide and reference documentation on
    the Fax REST API.


    If you have questions please contact us via our [support
    portal](https://support.sinch.com) and a team member will be happy to
    assist.


    {% admonition type="info" name="Note:" %}

    You must create an account on our support portal if you do not have one.

    {% /admonition %}


    ## Authentication


    For information on how to authenticate API requests we support two methods
    [Basic](https://developers.sinch.com/docs/fax/api-reference/authentication/basic.md)
    or
    [Oauth2](https://developers.sinch.com/docs/fax/api-reference/authentication/oauth.md)


    ## Global URL


    Sinch has a global server that will route your call to the appropriate
    geography region automatically:


    ```shell

    https://fax.api.sinch.com/

    ```


    or, you can also specify what location you want to call by prefixing the
    above global URL with one of the region codes in the table below:


    | Region            | URL                     |

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

    | US East Coast     | use1.fax.api.sinch.com  |

    | Europe            | eu1.fax.api.sinch.com   |

    | South America     | sae1.fax.api.sinch.com  |

    | South East Asia 1 | apse1.fax.api.sinch.com |

    | South East Asia 2 | apse2.fax.api.sinch.com |


    ## Formats


    By default, all API calls return a JSON response unless otherwise specified.


    ### Date time fields


    All date and time fields are in UTC format unless otherwise specified.


    ## Deletion and data retention


    In general we retain fax logs and media for 13 months and you can access
    that via the API.


    ## Errors & statuses


    Find error codes and explanations
    [here](https://developers.sinch.com/docs/fax/api-reference/fax/error-messages).


    ## Webhooks


    You can configure your service to use webhooks to send a request to you when
    faxes arrive or complete on your account.
  contact:
    name: Contact Fax API Team
    url: https://www.sinch.com/contact/
    email: faxteam@sinch.com
  license:
    url: https://www.sinch.com/toc
    name: MIT
servers:
  - url: https://fax.api.sinch.com/v3/projects/{projectId}
    description: v3.0 of the Fax API
    variables:
      projectId:
        description: The project with which you are working.
        default: YOUR_project_id
security:
  - BasicAuth: []
  - OAuth2: []
tags:
  - name: Faxes
    description: >-
      The Fax API allows you to send and receive faxes. You can send faxes to a
      single recipient or to multiple recipients. You can also receive faxes and
      download them.


      To send a TEST Outbound fax you can send a fax TO +19898989898.  This will
      emulate all aspects of a real fax without charging your account.
  - name: Notifications
    description: >-
      Webhooks allow you to get updates in real-time about the status of your
      faxes. Webhooks are triggered by events such as the completion of a fax,
      and transmit information about the state of that fax to you via HTTP(S) or
      email.

      HTTP webhooks are multipart/form-data POST requests, and should be
      processed like form submissions.


      ## Setting up webhooks


      Depending on the type of webhook, you can configure the callback URLs in a
      few ways:

        **Incoming fax notification**:

        - On your [Fax service](https://dashboard.sinch.com/fax/services) in the dashboard.
        - Using the [API when configuring your service](https://developers.sinch.com/docs/fax/api-reference/fax/services/createnotificationwebhook). This is required to receive notifications about incoming calls to your Sinch number.

        **Fax completed notification**:

        - By including the `callbackUrl` property in the request body when you send a fax via the `/faxes` endpoint.


      ### Retries


      If a webhook fails, we will automatically retry sending the fax up to 16
      times. There will be a back off before each retry, which increases as
      follows:


      | Retry number | Back off   |

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

      | 1            | 5 minutes  |

      | 2            | 10 minutes |

      | 3            | 20 minutes |

      | 4            | 30 minutes |

      | 5-16         | 6 hours    |
  - name: Fax to Email
    description: >-
      The Emails endpoint allows you to configure the Fax to Email
      functionality. Fax to Email allows you to send an email and then receive a
      fax on your Sinch number or send a fax and have it sent to your email
      address.

      The service supports sending incoming faxes to multiple email addresses
      and having many numbers associated with one email address.


      ## Setting up fax to email


      You can configure fax to email in two different places:

        - In the dashboard on a number-by-number basis or by adding an email address and associating many numbers to one email address.
        - Via the API when you create a number or update a number, or by using the email endpoint to set it up directly
        - Supported fax to email file types are Word, PDF, and TIF

      ## Fax to email example


      The following example shows how to configure Fax to Email using the API:
        1. Buy a number in the dashboard and assign it to a Fax service
        2. Add your email and associate it with the number you bought in step 1.

      ```json

      POST
      https://fax.api.sinch.com/v3/projects/{projectId}/services/{serviceId}/emails
       {
          "email": "user@domain.com",
          "phoneNumbers": [
             "+14155552222"
          ]
      }

      ```

      Now you can use your email client with the above email address to fax.


      ## Send a fax using email


      Make sure the email address you are sending from is added to your account.
      You can add it in the dashboard under [Fax to
      email](https://dashboard.sinch.com/fax/fax-to-email) or via the API.


      Send an email to {PhoneNumberToSendFaxTo}@sinchfax.com with the following:


      | Field | Description |

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

      | **Subject:** | If you have multiple phone numbers associated with the
      email address, enter the number you want to use. If left blank, the first
      number that we find will be used. |

      | **Body:** | By default, the email body is not used.  |

      | **Attachments** | Add any attachments you want to fax. If you want to
      specify the order of pages we recommend that you create one document with
      all pages in the correct order and attach that document. If you attach
      multiple documents we will merge them  into one document in the order we
      receive them. |



      ## Receive a fax using email


      When you receive a fax, we will send you an email with the following:

      | Field | Description |

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

      | **From:** | The number the fax was sent from, e.g.
      +15612600684@sinchfax.com |

      | **Subject:** | Fax received on {your sinch number the fax was sent to} |

      | **Body:** | The body will contain data such as number of pages or other
      relevant metadata of the fax. |


      There will be one PDF attachment with the fax content.


      ## Configuring your email system for best performance


      Make sure you allowlist `sinchfax.com` and `sinch.com` in your spam filter
      to ensure delivery to your inbox, both on client and server side.

      Ensure your mail server is setup correctly and not on spam lists.


      ## Encryption


      All emails are sent using TLS during transport from Sinch.
  - name: Cover pages
    description: >-
      You can add cover pages to Sinch Fax either via the API or the [Build
      dashboard](https://dashboard.sinch.com).


      A Fax service can have 0 or more cover pages configured.


      ### When cover pages are added


      #### Via dashboard


      In the **Send Fax** tab you can select the option to ***select a cover
      page from a drop down***. When one is selected it will use that cover page
      on all outbound faxes.


      **Note:** If you are using Fax to Email, this is currently the only way to
      add a cover page to your faxes.


      #### Via API


      When sending a fax using the API, you can specify `coverPageId` and supply
      your own cover page data.


      ### How to create a cover page


      Create a PDF that fits your brand. It should have all the standard static
      content you need to stay compliant. Insert tags that will be replaced at
      run time by us for dynamic content.


      #### Automatic fields


      If we find the tags described in the table below, we will replace these
      tokens with fax metadata.


      |Tag | Content | Example |Description |

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

      |{{from}}| string | +15557897890 | Your Sinch number that you used to send
      the fax. |

      |{{to}}| string | +15551231234 |  The number to which you are sending the
      fax. |

      |{{date}}| date | 2/4/2025 | The date when the fax was sent. |

      |{{pageCount}}| number | 52 | The total number of pages to be transmitted.
      |


      ### Specifying your own dynamic fields in API calls


      When sending faxes via API you can add any tags you like with `{{}}``
      syntax and set those in your app calls for cover page data.


      Example:
        If you would like to add the recipient's name and your own message on the cover page:

      ```json

      /// in your template pdf

      Fax to : {{to_name}}

      {{my_custom_message}}


      {
        ///other fax fields removed for clarity
        coverPageData: {
          "to_name": "Dr. John Smith",
          "my_custom_message": "I know you are busy please take on this patient"
          }
      }

      ```
  - name: Error Messages
    description: >-
      ## Fax Error Messages


      When your receive a callback from the fax api notifying you of a failure,
      it will contain two values

      that can help you understand what went wrong: an errorCode and an type.


      The type will give you a general idea of why the operation failed, whereas
      the errorCode describes the issue in more detail. Below we list the
      error_codes for the API, segmented by their corresponding error_type.


      ## General Error Messages


      Request errors are returned as HTTP status codes. The following table
      lists the possible error codes and their meaning.


      The type will give you a general idea of why the operation failed, whereas
      the errorCode describes the issue in more detail. Below we list the
      error_codes for the API, segmented by their corresponding error_type.


      ## Http Error Codes


      ### 400 - Bad Request


      ```json

      {
        "code": "404",
        "error": "Bad Request",
        "message": "
          The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
          It could be invalid JSON, missing required fields, or other issues."
      }

      ```


      ### 401 - Unauthorized


      Empty body, or you have the wrong API key, secret, or project.


      ### 402 - Payment required


      ```json

      {
        "code": "402",
        "error": "Payment required",
        "message": "You have reached 0 balance on your account please make a payment."
      }

      ```



      ### 404 - Not found


      ```json

      {
        "code": "404",
        "error": "Not found",
        "message": "The resource is not found, not available, or does not exist."
      }

      ```


      ### 422 - Unprocessable Content (Invalid parameters)


      ```json

      {
        "code": "422",
        "error": "Invalid parameters",
        "message": "The request could not be understood by the server due to malformed syntax.
           The client SHOULD NOT repeat the request without modifications."
        details: {
          fieldViolations: [
            {
              field: "to",
              description: "The (+15551) is not a valid phone number"
            }
          ]

        }
      ```


      ### 429 Rate limit exceeded


      Rate limit exceeded, please back off and try again later. If you need
      higher rate please contact support.



      ### 500 - Internal Server Error


      Probably no body, but if there is a body it will look like this:


      ```json

      {
        "code": "500",
        "error": "Internal service error",
        "message": "Most likely a temporary issue, please try again later. If the problem persists, please back of on this request and contact support."
      }

      ```


      ### 800 - URL Connection Error


      This non-http code will be used when there is an issue connecting to the
      designated callback URL. The response will look like this:


      ```json

      {
        "error": "Could not connect to URL: https://123.456.789.00"
      }

      ```



      ## Error object


      Please note that the response code is probably the most important part of
      the response, but the error object will contain more information about the
      error.

      Not all errors return this object, and the `details` object is not always
      present.
  - name: Services
    description: >
      A fax service identifies a set of configuration values. You can specify
      the service as a part of an API request or by associating a Sinch number
      with a service.


      This can be useful if you want to point a group of numbers to a particular
      incoming fax URL, or want to set the storage strategy for some of your
      numbers but not all of them.


      ## Dashboard

      You can manage all your fax services and their settings via the
      [Dashboard](https://dashboard.sinch.com/fax/services).


      ## Sending a test fax


      To send a TEST Inbound fax event in the Dashboard, enter the
      `IncomingWebhookUrl` on the Incoming tab and click **Save**.  Then click
      the **SEND TEST REQUEST** button. This will emulate all aspects of a real
      INCOMING fax event without charging your account.
webhooks:
  incomingFax:
    post:
      security:
        - BasicAuth: []
      operationId: incomingFaxEvent
      tags:
        - Faxes
        - Notifications
      summary: Incoming fax event
      description: >-
        This webhook is triggered when a fax is received on a Sinch number
        associated with a service. The webhook will contain information about
        the fax, such as the sender, the recipient, and the content of the fax.
        You set the callback URL for incoming fax events on the service, either
        through the [dashboard](https://dashboard.sinch.com/fax/services) or
        using the [service
        API](https://developers.sinch.com/docs/fax/api-reference/fax/services/createnotificationwebhook).


        ### Example payloads


        Multipart/form-data request payloads are encoded as forms with a content
        type of JSON and the actual fax content as a **'file' application/pdf
        attachment**.


        Application/json request payloads are a JSON object with the file
        encoded as a base64 string as part of the JSON object.
      requestBody:
        content:
          multipart/form-data:
            schema:
              allOf:
                - type: object
                  properties:
                    event:
                      type: string
                      description: The value is always `INCOMING_FAX` for this event.
                      enum:
                        - INCOMING_FAX
                      default: INCOMING_FAX
                    file:
                      description: The fax content as a PDF attachment to the body
                      type: string
                      format: binary
                      contentMediaType: application/pdf
                      contentEncoding: binary
                - $ref: '#/components/schemas/GenericEvent'
            encoding:
              file:
                contentType: application/pdf
              fax:
                contentType: application/json
              event:
                contentType: application/json
            example:
              event: INCOMING_FAX
              eventTime: '2021-11-01T23:25:67Z'
              fax:
                id: 01HDFHACK1YN7CCDYRA6ZRMA8Z
                direction: INBOUND
                from: '+14155552222'
                to: '+14155553333'
                numberOfPages: 1
                status: COMPLETED
                price:
                  amount: '0.00'
                  currencyCode: USD
                createTime: '2021-11-01T23:25:67Z'
                completedTime: '2021-11-01T23:25:67Z'
                projectId: YOUR_PROJECT_ID
                serviceId: YOUR_SERVICE_ID
              file: '{application/pdf}'
          application/json:
            schema:
              type: object
              properties:
                event:
                  allOf:
                    - $ref: '#/components/schemas/WebhookEvents'
                  description: Always `INCOMING_FAX` for this event.
                  enum:
                    - INCOMING_FAX
                  default: INCOMING_FAX
                eventTime:
                  description: Time of the event.
                  type: string
                  format: date-time
                fax:
                  description: The incoming fax.
                  $ref: '#/components/schemas/Fax'
                file:
                  description: The base64 encoded file.
                  type: string
                  example: '{base64_encodedData}'
                fileType:
                  description: The file type of the attached file.
                  type: string
                  example: PDF
            example:
              event: INCOMING_FAX
              eventTime: '2021-11-01T23:25:67Z'
              fax:
                id: 01HDFHACK1YN7CCDYRA6ZRMA8Z
                direction: INBOUND
                from: '+14155552222'
                to: '+14155553333'
                numberOfPages: 1
                status: COMPLETED
                price:
                  amount: '0.00'
                  currencyCode: USD
                createTime: '2021-11-01T23:25:67Z'
                completedTime: '2021-11-01T23:25:67Z'
                projectId: YOUR_PROJECT_ID
                serviceId: YOUR_SERVICE_ID
              file: '{base64_encodedData}'
              fileType: PDF
      responses:
        '200':
          description: Returns a 200 OK response if the webhook was received successfully.
  faxCompleted:
    post:
      security:
        - BasicAuth: []
      summary: Fax completed
      description: >-
        Triggered when the fax has been completed. The callback will contain
        information about the fax, such as the sender, the recipient, and the
        content of the fax. You must set the callback URL where you want the
        callback sent when you make a send fax request.
      operationId: faxCompletedCallback
      tags:
        - Notifications
        - Faxes
      requestBody:
        content:
          multipart/form-data:
            schema:
              allOf:
                - type: object
                  properties:
                    event:
                      type: string
                      description: Always fax completed for this event.
                      enum:
                        - FAX_COMPLETED
                      default: FAX_COMPLETED
                    file:
                      description: The fax content as pdf attachment to the body
                      type: string
                      format: binary
                      contentMediaType: application/pdf
                      contentEncoding: binary
                - $ref: '#/components/schemas/GenericEvent'
            encoding:
              file:
                contentType: application/pdf
              fax:
                contentType: application/json
              event:
                contentType: application/json
            example:
              event: FAX_COMPLETED
              eventTime: '2021-11-01T23:25:67Z'
              fax:
                id: 01HDFHACK1YN7CCDYRA6ZRMA8Z
                direction: INBOUND
                from: '+14155552222'
                to: '+14155553333'
                numberOfPages: 1
                status: COMPLETED
                price:
                  amount: '0.07'
                  currencyCode: USD
                createTime: '2021-11-01T23:25:67Z'
                completedTime: '2021-11-01T23:25:67Z'
                callbackUrl: https://www.my-website.com/callback
                callbackUrlContentType: multipart/form-data
                imageConversionMethod: HALFTONE
                projectId: YOUR_PROJECT_ID
                serviceId: YOUR_SERVICE_ID
              file: '{application/pdf}'
          application/json:
            schema:
              type: object
              properties:
                event:
                  allOf:
                    - $ref: '#/components/schemas/WebhookEvents'
                  description: Always `FAX_COMPLETED` for this event.
                  enum:
                    - FAX_COMPLETED
                  default: FAX_COMPLETED
                eventTime:
                  description: Time of the event.
                  type: string
                  format: date-time
                fax:
                  description: The incoming fax.
                  $ref: '#/components/schemas/Fax'
                files:
                  type: array
                  items:
                    $ref: '#/components/schemas/FaxBase64File'
            example:
              event: FAX_COMPLETED
              eventTime: '2021-11-01T23:25:67Z'
              fax:
                id: 01HDFHACK1YN7CCDYRA6ZRMA8Z
                direction: INBOUND
                from: '+14155552222'
                to: '+14155553333'
                numberOfPages: 1
                status: COMPLETED
                price:
                  amount: '0.07'
                  currencyCode: USD
                createTime: '2021-11-01T23:25:67Z'
                completedTime: '2021-11-01T23:25:67Z'
                callbackUrl: https://www.my-website.com/callback
                callbackUrlContentType: application/json
                projectId: YOUR_PROJECT_ID
                serviceId: YOUR_SERVICE_ID
              files:
                - file: '{base64ecnodeddata}'
                  fileType: PDF
      responses:
        '200':
          description: Returns a 200 OK response if the webhook was received successfully.
paths:
  /faxes:
    post:
      tags:
        - Faxes
      summary: Send a fax
      description: >-
        Create and send a fax.


        Fax content may be supplied via one or more files or URLs of supported
        filetypes.


        This endpoint supports the following content types for the fax payload:

          - Multipart/form-data
          - Application/json

        We will however always return a fax object in the response in
        application json. If you supply a callbackUrl the callback will be sent
        as multipart/form-data

        with the content of the fax as an attachment to the body, *unless* you
        specify callbackUrlContentType as application/json.


        #### file(s)

        Files may be included in the POST request as multipart/form-data parts.


        #### contentUrl

        Any URL on the Internet (including ones with basic authentication), and
        we'll pull it down and make it a fax. This might be useful to you if
        you're using a web framework for templates and creating fax files.


        Please note: If you are passing fax a secure URL (starting with
        `https://`), make sure that your SSL certificate (including your
        intermediate cert, if you have one) is installed properly, valid, and
        up-to-date.
      operationId: sendFax
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - to
              allOf:
                - type: object
                  properties:
                    to:
                      description: >-
                        When you send a fax you can specify a single number or a
                        list of numbers separated by ;.

                        Please note that if you specify a list of numbers, the
                        fax will be sent to all numbers and a Fax resource will
                        be created for each number.


                        When you receive a fax, this is the number where the fax
                        is sent to.
                      $ref: '#/components/schemas/PhoneNumber'
                    file:
                      description: >-
                        The file(s) you want to send as a fax as body
                        attachment.
                      type: string
                      format: binary
                - $ref: '#/components/schemas/Fax'
            encoding:
              files:
                contentType: application/octet-stream
            examples:
              SendFax:
                $ref: '#/components/examples/SendWebPageAsFax'
              SendFileAsFaxWithCoverPage:
                $ref: '#/components/examples/SendFileAsFaxWithCoverPage'
              SendFileAsFax:
                $ref: '#/components/examples/SendFileAsFax'
          application/json:
            schema:
              required:
                - to
              allOf:
                - type: object
                  properties:
                    to:
                      description: >-
                        When you send a fax you can specify a single number or a
                        list of numbers separated by ;.

                        Please note that if you specify a list of numbers, the
                        fax will be sent to all numbers and a Fax resource will
                        be created for each number.


                        When you receive a fax, this is the number where the fax
                        is sent to.
                      $ref: '#/components/schemas/PhoneNumber'
                    from:
                      $ref: '#/components/schemas/PhoneNumber'
                      description: >-
                        The number you want to send a fax from. This number must
                        be associated with your account.

                        If you do not specify a from number, we will use the
                        first number associated with your account.
                - $ref: '#/components/schemas/FaxBase64Array'
                - $ref: '#/components/schemas/Fax'
            examples:
              SendFileAsFaxWithCoverPage:
                $ref: '#/components/examples/SendFileAsFaxWithCoverPage'
              SendWebPageAsFax:
                $ref: '#/components/examples/SendWebPageAsFax'
              SendFileAsFaxJson:
                $ref: '#/components/examples/SendFileAsFaxJson'
      responses:
        '200':
          description: The created fax
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fax'
              example:
                id: 01HDF5S9P29WC29J578J8EKC1C
                direction: OUTBOUND
                to: '+1234567890'
                status: IN_PROGRESS
                headerTimeZone: America/New_York
                retryDelaySeconds: 60
                callbackUrl: https://my.callback.server
                projectId: YOUR_PROJECT_ID
                serviceId: YOUR_SERVICE_ID
                maxRetries: 3
                createTime: '2023-10-23T21:06:52.231Z'
                headerPageNumbers: true
                contentUrl:
                  - www.google.com
                imageConversionMethod: HALFTONE
    get:
      tags:
        - Faxes
      summary: List faxes
      operationId: getFaxes
      description: >-
        List faxes sent (OUTBOUND) or received (INBOUND), set parameters to
        filter the list.

        Example: Return calls made between 1st of January 2021 and  10th of
        January 2021.

        ```
         created>=2021-01-01&startTime<=2021-01-10
        ```
      parameters:
        - name: serviceId
          in: query
          description: Limits results to faxes that were sent using the specified service.
          schema:
            type: string
            example: YOUR_SERVICE_ID
        - name: createTime
          in: query
          description: >-
            Filter calls based on  `createTime`. If you make the query more
            precise, fewer results will be returned.

            For example, `2021-02-01` will return all calls from the first of
            February 2021, and `2021-02-01T14:00:00Z` will return all calls
            after 14:00 on the first of February.

            This field also supports `<=` and `>=` to search for calls in a
            range `?createTime>=2021-10-01&startTime<=2021-10-30` to get a list
            of calls for all of October 2021.

            It is also possible to submit partial dates. For example,
            `createTime=2021-02` will return all calls for February 2021.


            If not value is submitted, the default value is the prior week.
          schema:
            type: string
            format: date-time
        - name: direction
          in: query
          description: Limits results to faxes with the specified direction.
          schema:
            $ref: '#/components/schemas/FaxDirection'
          example: OUTBOUND
        - name: status
          in: query
          description: Limits results to faxes with the specified status.
          schema:
            $ref: '#/components/schemas/FaxStatus'
          example: COMPLETED
        - name: to
          in: query
          description: >-
            A phone number that you want to use to filter results. The parameter
            search with startsWith, so you can pass a partial number to get all
            faxes sent to numbers that start with the number you passed.
          schema:
            $ref: '#/components/schemas/PhoneNumber'
          example: '+14155552222'
        - name: from
          in: query
          description: >-
            A phone number that you want to use to filter results.  The
            parameter search with startsWith, so you can pass a partial number
            to get all faxes sent to numbers that start with the number you
            passed.
          schema:
            $ref: '#/components/schemas/PhoneNumber'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Result of the query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFaxesObject'
  /faxes/{id}:
    get:
      tags:
        - Faxes
      summary: Get fax
      description: Get fax information using the ID number of the fax.
      operationId: getFaxInfoPerId
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The fax
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fax'
              example:
                id: 01HDF5S9P29WC29J578J8EKC1C
                direction: OUTBOUND
                to: '+1234567890'
                status: IN_PROGRESS
                headerTimeZone: America/New_York
                retryDelaySeconds: 60
                callbackUrl: https://my.callback.server
                projectId: YOUR_PROJECT_ID
                serviceId: YOUR_SERVICE_ID
                maxRetries: 3
                createTime: '2023-10-23T21:06:52.231Z'
                headerPageNumbers: true
                contentUrl:
                  - www.google.com
                imageConversionMethod: HALFTONE
                hasFile: false
  /faxes/{id}/file:
    delete:
      tags:
        - Faxes
      summary: Delete fax content
      description: |-
        Delete the fax content for a fax using the ID number of the fax.
        Please note that this only deletes the content of the fax from storage.
      operationId: deleteFaxContentById
      parameters:
        - $ref: '#/components/parameters/Id'
      responses:
        '204':
          description: The fax content was deleted.
  /faxes/{id}/file.{fileFormat}:
    get:
      tags:
        - Faxes
      summary: Download fax content
      description: Download the fax content.
      operationId: getFaxFileById
      parameters:
        - $ref: '#/components/parameters/Id'
        - name: fileFormat
          in: path
          required: true
          schema:
            type: string
            enum:
              - pdf
            default: pdf
            x-enumDescriptions:
              pdf: PDF format
          description: The file format to download. Currently only PDF is supported.
          example: pdf
      responses:
        '200':
          description: >-
            A file for the fax you requested will be returned in the format you
            specified.
          content:
            application/pdf:
              schema:
                description: >-
                  A PDF file named 'fax-1234.pdf' containing all files sent for
                  fax #1234.
                type: string
                format: binary
  /services:
    post:
      description: >-
        Creates a new service that you can use to set default configuration
        values.
      operationId: createService
      summary: Create a service
      tags:
        - Services
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service'
      responses:
        '201':
          description: The newly created service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
    get:
      description: Get a list of services for a project.
      summary: List services
      operationId: listServices
      tags:
        - Services
      parameters:
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
            example: 20
            maximum: 1000
          description: Number of services to return on each request.
        - name: page
          in: query
          schema:
            type: string
          description: >-
            Optional. The page to fetch. If not specified, the first page will
            be returned.
      responses:
        '200':
          $ref: '#/components/responses/ServiceList'
  /services/{id}:
    get:
      description: Get a service resource.
      summary: Get a service
      operationId: getService
      tags:
        - Services
      parameters:
        - name: id
          description: The service ID you want to update.
          required: true
          schema:
            type: string
          in: path
      responses:
        '200':
          description: >-
            The requested service, or an
            [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
    patch:
      description: Update settings on the service.
      summary: Update a Service
      operationId: updateService
      parameters:
        - name: id
          required: true
          description: The service ID you want to update.
          schema:
            type: string
          in: path
      tags:
        - Services
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service'
      responses:
        '200':
          description: >-
            The updated service, or an
            [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
    delete:
      description: Removes a service from your project.
      operationId: removeService
      summary: Remove a service
      tags:
        - Services
      parameters:
        - name: id
          description: The serviceId you want to remove from your project.
          required: true
          in: path
          schema:
            type: string
      responses:
        '204':
          description: >-
            The service removed from the project, or an
            [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)
  /services/{id}/coverPages:
    parameters:
      - name: id
        description: the serviceId
        required: true
        in: path
        schema:
          type: string
    post:
      description: Add a cover page to your service
      summary: Add cover page
      operationId: addCoverPage
      tags:
        - Cover pages
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CoverPage'
      responses:
        '200':
          description: >-
            The added  coverpage, or an
            [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverPage'
    get:
      description: List all cover page to a service
      summary: List cover pages
      operationId: listCoverPages
      tags:
        - Cover pages
      responses:
        '200':
          description: >-
            List of coverpages
            [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      coverPages:
                        description: List of cover pages
                        type: array
                        items:
                          $ref: '#/components/schemas/CoverPage'
                  - $ref: '#/components/schemas/Pagination'
  /services/{id}/coverPages/{coverPageId}:
    parameters:
      - name: id
        description: The serviceId containing the cover page you want to work with.
        required: true
        in: path
        schema:
          type: string
      - name: coverPageId
        in: path
        required: true
        schema:
          type: string
          description: The coverPageId you want to work with.
    delete:
      tags:
        - Cover pages
      operationId: deleteCoverPage
      summary: Delete a cover page
      description: Remove delete a cover page from a service.
      responses:
        '204':
          description: The cover page was deleted.
    get:
      tags:
        - Cover pages
      operationId: getCoverPage
      summary: Get a cover page
      description: Get a cover page by ID.
      responses:
        '200':
          description: >-
            The requested cover page, or an
            [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverPage'
  /services/{id}/numbers:
    get:
      description: List numbers for a service.
      summary: List numbers for service
      operationId: listNumbersForService
      tags:
        - Services
      parameters:
        - name: id
          required: true
          description: The serviceId containing the numbers you want to list.
          in: path
          schema:
            type: string
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
            example: 20
            maximum: 1000
          description: Number of items to return on each page.
        - name: page
          in: query
          schema:
            type: string
          description: >-
            Optional. The page to fetch. If not specified, the first page will
            be returned.
      responses:
        '200':
          description: >-
            The list of numbers, or an
            [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      numbers:
                        description: List of phone numbers
                        type: array
                        items:
                          $ref: '#/components/schemas/ServicePhoneNumber'
                  - $ref: '#/components/schemas/Pagination'
  /services/{id}/numbers/{phoneNumber}/emails:
    parameters:
      - name: phoneNumber
        description: The phone number you want to get emails for.
        required: true
        in: path
        schema:
          type: string
          description: A phone number in e.164 format.
          example: '+15612600684'
      - name: id
        description: The serviceId containing the numbers you want to list.
        required: true
        in: path
        schema:
          type: string
    get:
      summary: List emails for a number
      description: List any emails for a number.
      operationId: getEmailsForNumber
      tags:
        - Fax to Email
      parameters:
        - name: page
          in: query
          description: >-
            The page to fetch. If not specified, the first page will be
            returned.
          schema:
            type: integer
            default: 1
            example: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 100
            example: 20
            maximum: 1000
          description: Number of items to return on each page.
      responses:
        '200':
          description: A list of emails associated with the number.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      emails:
                        description: List of emails numbers
                        type: array
                        items:
                          type: string
                          format: email
                  - $ref: '#/components/schemas/Pagination'
  /services/{serviceId}/emails:
    get:
      description: List emails for the project.
      summary: List emails
      operationId: getEmailsForProject
      tags:
        - Fax to Email
      parameters:
        - name: serviceId
          in: path
          description: The serviceId containing the emails you want to list.
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: >-
            The page to fetch. If not specified, the first page will be
            returned.
          schema:
            type: integer
            default: 1
            example: 1
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 100
            example: 20
            maximum: 1000
          description: Number of items to return on each page.
      responses:
        '200':
          description: A list of emails associated with the project.
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      emails:
                        description: List of emails
                        type: array
                        items:
                          $ref: '#/components/schemas/Email'
                  - $ref: '#/components/schemas/Pagination'
    post:
      description: >-
        Add an email to the specified service to be used for sending and
        receiving faxes. Default settings for permissions parameter is `both`.
      summary: Add an email
      operationId: createEmailForProject
      tags:
        - Fax to Email
      parameters:
        - name: serviceId
          in: path
          description: The serviceId to which you want to add the email.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Email'
            example:
              email: user@domain.com
              phoneNumbers:
                - number: '+14155552222'
                  permissions: both
      responses:
        '201':
          description: The added email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
  /services/{serviceId}/emails/{email}:
    parameters:
      - name: serviceId
        description: The serviceId containing the email you want to work with.
        required: true
        in: path
        schema:
          type: string
      - name: email
        description: The email you want to work with.
        required: true
        in: path
        schema:
          type: string
    put:
      description: Set the numbers for an email.
      operationId: updateEmail
      summary: Update numbers for email
      tags:
        - Fax to Email
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - phoneNumbers
              properties:
                phoneNumbers:
                  description: List of numbers
                  type: array
                  items:
                    $ref: '#/components/schemas/Number'
            example:
              phoneNumbers:
                - number: '+14155552222'
                  permissions: both
      responses:
        '200':
          description: The added email
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
    delete:
      tags:
        - Fax to Email
      summary: Remove email
      description: >-
        Delete an email and associated numbers to that email to disable that
        email from sending and receiving faxes.
      operationId: deleteEmail
      responses:
        '204':
          description: 'No content: **The email was deleted**'
  /services/{serviceId}/emails/{email}/numbers:
    parameters:
      - name: serviceId
        description: The serviceId containing the email you want to work with.
        required: true
        in: path
        schema:
          type: string
      - name: email
        description: The email you want to get numbers for.
        required: true
        in: path
        schema:
          type: string
      - name: pageSize
        in: query
        schema:
          type: integer
          default: 20
          example: 20
          maximum: 1000
        description: Number of items to return on each page.
      - name: page
        in: query
        schema:
          type: string
        description: >-
          Optional. The page to fetch. If not specified, the first page will be
          returned.
    get:
      description: Get  configured numbers for an email
      summary: Get numbers for email
      operationId: getNumbersByEmail
      tags:
        - Fax to Email
      responses:
        '200':
          description: A list of numbers associated with the email
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      phoneNumbers:
                        description: List of numbers
                        type: array
                        items:
                          $ref: '#/components/schemas/ServicePhoneNumber'
                  - $ref: '#/components/schemas/Pagination'
components:
  examples:
    SendWebPageAsFax:
      summary: Send a web page as a fax
      value:
        to: '+14155552222'
        contentUrl: https://developers.sinch.com/fax/fax.pdf
    SendFileAsFax:
      summary: Send a file as a fax
      value:
        to: '+14155552222'
        file: //path/to/file.pdf
    SendFileAsFaxWithCoverPage:
      summary: Send a fax with cover page
      value:
        to: '+14155552222'
        file: //path/to/file.pdf
        coverPageId: 12312kj312kl3j12k3j
        coverPageData:
          message: To Dr. Smith regarding referral
    SendFileAsFaxJson:
      summary: Send a file as a fax
      value:
        to: '+14155552222'
        files:
          - file: '{base64EncodedData}'
            fileType: PDF
  responses:
    ServiceList:
      description: >-
        List of services, or an
        [Error](https://developers.sinch.com/docs/fax/api-reference/status-codes)
      content:
        application/json:
          schema:
            allOf:
              - type: object
                properties:
                  services:
                    description: List of services.
                    type: array
                    items:
                      $ref: '#/components/schemas/Service'
              - $ref: '#/components/schemas/Pagination'
  schemas:
    Number:
      description: A phone number and its permissions.
      type: object
      properties:
        number:
          $ref: '#/components/schemas/PhoneNumber'
        permissions:
          type: string
          description: >-
            Allows you to set permissions for sending and receiving faxes to
            this email/phone number combination. Default value is `both`.
          x-enumDescriptions:
            both: >-
              Allows the email to send and receive faxes to this email/phone
              number combination.
            send: >-
              Allows the email to only send faxes to this email/phone number
              combination.
            receive: >-
              Allows the email to only receive faxes from this email/phone
              number combination.
          enum:
            - both
            - send
            - receive
          default: both
    Email:
      type: object
      required:
        - email
        - phoneNumbers
      properties:
        email:
          type: string
          format: email
          example: user@domain.com
        phoneNumbers:
          description: Numbers you want to associate with this email.
          type: array
          items:
            $ref: '#/components/schemas/Number'
        projectId:
          readOnly: true
          x-version: 1
          allOf:
            - $ref: '#/components/schemas/ProjectId'
    FaxDirection:
      type: string
      description: The direction of the fax.
      readOnly: true
      enum:
        - OUTBOUND
        - INBOUND
      x-enumDescriptions:
        OUTBOUND: The fax was sent by you via the API.
        INBOUND: The fax was received on one of your numbers.
      example: OUTBOUND
    Fax:
      type: object
      properties:
        id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/FaxId'
        direction:
          allOf:
            - $ref: '#/components/schemas/FaxDirection'
          readOnly: true
        from:
          allOf:
            - $ref: '#/components/schemas/PhoneNumber'
          readOnly: false
          description: >-
            For `INBOUND` faxes, this is the number where the fax is sent from

            For `OUTBOUND` faxes, this is the Sinch number you want to have as
            sender
        to:
          allOf:
            - $ref: '#/components/schemas/PhoneNumber'
          readOnly: false
          description: >-
            For `INBOUND` faxes, this is the Sinch number someone sent the fax
            to.

            For `OUTBOUND` faxes, this is the phone number you want to send a
            fax to.


            You can add multiple numbers by adding them as an array. For
            example:

              application/json

              ```json
              "to": ["+14155552222", "+14155553333"]
              ```

              multipart/form
              ```json
              to=+14155552222&to=+14155553333

              ```
        contentUrl:
          anyOf:
            - type: string
              format: url
              description: Single URL
              example: https://example.com/fax.pdf
            - type: array
              items:
                type: string
              description: Multiple URLs
              example:
                - www.google.com
                - www.sinch.com
          writeOnly: true
          format: URL
          description: >-
            Give us any URL on the Internet (including ones with basic
            authentication)

            At least one file or contentUrl parameter is required.

            Please note: If you are passing fax a secure URL (starting with
            https://), make sure that your SSL certificate (including your
            intermediate cert, if you have one) is installed properly, valid,
            and up-to-date.

            If the file parameter is specified as well, content from URLs will
            be rendered before content from files.


            You can add multiple URLs by adding them as an array them with a
            comma when posting as multipart/form-data


            For example: "https://developers.sinch.com/fax/fax.pdf,
            https://developers.sinch.com/" or if posting JSON `"contentUrl":
            ["https://developers.sinch.com/fax/fax.pdf",
            "https://developers.sinch.com/"]`
          example: https://developers.sinch.com/fax/fax.pdf
        numberOfPages:
          type: integer
          readOnly: true
          description: The number of pages in the fax.
        status:
          $ref: '#/components/schemas/FaxStatus'
        price:
          description: >-
            The total price for this fax. This field is populated after the
            final fax price is calculated.
          allOf:
            - $ref: '#/components/schemas/Money'
          readOnly: true
        barCodes:
          description: >-
            The bar codes found in the fax. This field is populated when Sinch
            detects bar codes on incoming faxes.
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/BarCode'
        createTime:
          readOnly: true
          type: string
          format: date-time
          description: >-
            A timestamp representing the time when the initial API call was
            made.
        completedTime:
          type: string
          format: date-time
          readOnly: true
          description: >-
            If the job is complete, this is a timestamp representing the time
            the job was completed.
        pagesSentSuccessfully:
          type: integer
          description: >-
            The number of pages successfully sent to the receiving side in the
            fax.
          readOnly: true
          example: 3
        headerText:
          description: >-
            Text that will be displayed at the top of each page of the fax. 50
            characters maximum. Default header text is "-". Note that the header
            is not applied until the fax is transmitted, so it will not appear
            on fax PDFs or thumbnails.
          type: string
          maximum: 50
          default: ''
        headerPageNumbers:
          type: boolean
          description: >-
            If true, page numbers will be displayed in the header. Default is
            true.
          default: true
        headerTimeZone:
          type: string
          format: timezone
          description: >-
            A [TZ database
            name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
            string specifying the timezone for the header timestamp.
          default: America/New_York
        retryDelaySeconds:
          description: >-
            The number of seconds to wait between retries if the fax is not yet
            completed.
          type: integer
          minimum: 30
          maximum: 300
          default: 60
        labels:
          x-version: 2
          description: >-
            You can use this to attach labels to your call that you can use in
            your BI solutions.
          allOf:
            - $ref: '#/components/schemas/Labels'
          example:
            customerId: '1234'
            customerName: John Doe
        callbackUrl:
          type: string
          description: >-
            The URL to which a callback will be sent when the fax is completed.
            The callback will be sent as a POST request with a JSON body. The
            callback will be sent to the URL specified in the `callbackUrl`
            parameter, if provided, otherwise it will be sent to the URL
            specified in the `callbackUrl` field of the Fax Service object.
          format: URL
          example: https://www.my-website.com/callback
        callbackUrlContentType:
          description: The content type of the callback.
          type: string
          default: multipart/form-data
          enum:
            - multipart/form-data
            - application/json
          x-enumDescriptions:
            multipart/form-data: >-
              The callback will be sent as a multipart/form-data request with
              files as attachments to the body.
            application/json: >-
              The callback will be sent as a JSON request with the files as
              base64 encoded strings in the JSON object.
        imageConversionMethod:
          $ref: '#/components/schemas/ImageConversionMethod'
        errorType:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/ErrorType'
        errorCode:
          readOnly: true
          type: integer
          description: >-
            One of the error numbers listed in the [Fax Error Messages
            section](https://developers.sinch.com/docs/fax/api-reference/fax/error-messages).
        errorMessage:
          readOnly: true
          type: string
          description: >-
            One of the error codes listed in the [Fax Error Messages
            section](https://developers.sinch.com/docs/fax/api-reference/fax/error-messages).
        maxRetries:
          readOnly: false
          type: integer
          description: >-
            | The number of times the fax will be retired before cancel. Default
            value is set in your fax service.

            | The maximum number of retries is 5.
          maximum: 5
          minimum: 0
        retryCount:
          readOnly: true
          type: integer
          description: The number of times the fax has been retried.
        hasFile:
          readOnly: true
          type: string
          description: >-
            Only shown on the fax result. This indicates if the content of the
            fax is stored with Sinch. (true or false)
        resolution:
          $ref: '#/components/schemas/Resolution'
        coverPageId:
          type: string
          description: The cover page id you want to use for the fax
        coverPageData:
          $ref: '#/components/schemas/CoverPageData'
        inProgressNotifications:
          type: boolean
          description: >-
            If set to `true`, you will receive a webhook notification for each
            page sent on an outbound fax.
          default: false
        projectId:
          readOnly: true
          x-version: 1
          allOf:
            - $ref: '#/components/schemas/ProjectId'
        serviceId:
          readOnly: false
          x-version: 1
          allOf:
            - $ref: '#/components/schemas/ServiceId'
    FaxBase64Array:
      description: An array of base64 encoded files
      type: object
      properties:
        files:
          type: array
          description: An array of base64 encoded files
          items:
            $ref: '#/components/schemas/FaxBase64File'
    FaxBase64File:
      type: object
      properties:
        file:
          type: string
          format: base64
          contentEncoding: base64
          description: >-
            When application/json Base64 encoded file content, this is only
            present when using application/json for request/response.
          example: '{base64-encoded content}'
        fileType:
          type: string
          description: >-
            When request/response is application json and file is part of
            payload. This is the file type of the file.
          enum:
            - DOCX
            - PDF
            - TIF
            - JPG
            - TXT
            - HTML
            - PNG
          x-enumDescriptions:
            DOCX: Microsoft Word
            PDF: PDF
            TIF: TIFF
            JPG: JPEG
            TXT: Text
            HTML: HTML
            PNG: PNG
    BarCode:
      type: object
      description: >-
        Sinch will scan all pages of all incoming faxes for Code-128 and
        DataMatrix bar codes and include this information in webhook requests
        and via the API.
      properties:
        type:
          type: string
          description: The type of barcode found.
          enum:
            - CODE_128
            - DATA_MATRIX
          x-enumDescriptions:
            CODE_128: Code-128 barcode.
            DATA_MATRIX: DataMatrix barcode.
        page:
          description: The page number on which the barcode was found.
          type: integer
        value:
          description: The  information of the barcode.
          type: string
    ListFaxesObject:
      type: object
      allOf:
        - type: object
          description: A list of faxes with pagination information.
          properties:
            faxes:
              type: array
              description: An array of faxes
              items:
                $ref: '#/components/schemas/Fax'
        - $ref: '#/components/schemas/Pagination'
    CoverPage:
      description: A cover page resource
      type: object
      required:
        - file
        - name
      properties:
        id:
          type: string
          format: ulid
          readOnly: true
          description: ID of the cover page
        name:
          description: The friendly name of the cover page.
          example: Acme Company cover page
        file:
          type: object
          required:
            - fileContent
            - fileType
          properties:
            fileContent:
              type: string
              format: base64
              contentEncoding: base64
              description: A PDF Cover encoded as base64
            fileType:
              type: string
              enum:
                - PDF
              description: For now only PDF is supported.
              x-enumDescriptions:
                PDF: A PDF file.
              default: PDF
          description: A PDF Cover encoded as base64
        projectId:
          allOf:
            - $ref: '#/components/schemas/ProjectId'
          readOnly: true
        serviceId:
          allOf:
            - $ref: '#/components/schemas/ServiceId'
          readOnly: true
        createdTime:
          type: string
          format: date-time
          readOnly: true
          description: The date and time the cover page was created.
        updatedTime:
          type: string
          readOnly: true
          format: date-time
          description: The date and time the cover page was updated.
    Service:
      type: object
      description: >-
        You can use the default created service, or create multiple services
        within the same project to have different default behavior for all your
        different faxing use cases.
      properties:
        id:
          $ref: '#/components/schemas/ServiceId'
        name:
          type: string
          description: A friendly name for the service. Maximum is 60 characters.
          example: Default service
          default: Default service
        incomingWebhookUrl:
          type: string
          x-version: 1
          description: >-
            The URL to which Sinch will post when someone sends a fax to your
            Sinch number. To accept incoming faxes this must be set and your
            Sinch phone number must be configured to receive faxes.
          readOnly: false
          example: https://yourserver/incomingFax
        webhookContentType:
          description: The content type of the webhook.
          type: string
          default: multipart/form-data
          enum:
            - multipart/form-data
            - application/json
          x-enumDescriptions:
            multipart/form-data: >-
              The webhook will be sent as a multipart/form-data request. Files
              are sent as attachments to the body.
            application/json: >-
              The webhook will be sent as a JSON request. Files are sent as
              base64 encoded strings in the JSON object.
        defaultForProject:
          x-version: 1
          type: boolean
          format: string
          description: >-
            If set to true this is the service used to create faxes when no
            serviceId is specified in the API endpoints.
          default: false
          x-internal: >-
            When an account and project is created, a default service for Voice
            should be created, and the test number should be assigned to this
            service
        defaultFrom:
          x-version: 1
          type: string
          description: >-
            One of your Sinch numbers connected to this service or any of your
            verified numbers.
        numberOfRetries:
          type: integer
          description: >-
            The number of times to retry sending a fax if it fails. Default is
            3. Maximum is 5.
          default: 3
        retryDelaySeconds:
          description: >-
            The number of seconds to wait between retries if the fax is not yet
            completed.
          type: integer
          minimum: 30
          maximum: 300
          default: 60
        imageConversionMethod:
          $ref: '#/components/schemas/ImageConversionMethod'
        coverPageId:
          type: string
          format: ulid
          description: If a value it will always add that cover page id to outbound faxes
          x-internal: in ui this will be a select list of the pages on the service
        saveOutboundFaxDocuments:
          description: Save fax documents with Sinch when you send faxes
          type: boolean
          default: true
        saveInboundFaxDocuments:
          description: Save fax documents with Sinch when you receive faxes
          type: boolean
          default: true
        scanIncomingBarcodes:
          type: boolean
          description: If set to true, barcodes will be detected on incoming faxes.
          default: false
        inProgressNotifications:
          type: boolean
          description: >-
            If set to `true`, you will receive a webhook notification for each
            page sent on an outbound fax.
          default: false
        projectId:
          $ref: '#/components/schemas/ProjectId'
          readOnly: true
        resolution:
          $ref: '#/components/schemas/Resolution'
    ImageConversionMethod:
      type: string
      description: >-
        Determines how documents are converted to black and white on OUTBOUND
        faxes only.  Image conversion is not done on INBOUND faxes. Defaults to
        value selected on Fax Service object.
      enum:
        - HALFTONE
        - MONOCHROME
      x-enumDescriptions:
        HALFTONE: Converts the image to halftone.
        MONOCHROME: Converts the image to monochrome.
      default: HALFTONE
    ServicePhoneNumber:
      type: object
      properties:
        phoneNumber:
          $ref: '#/components/schemas/PhoneNumber'
        projectId:
          $ref: '#/components/schemas/ProjectId'
          readOnly: true
        serviceId:
          $ref: '#/components/schemas/ServiceId'
          readOnly: true
    FaxId:
      type: string
      readOnly: true
      description: The id of a fax
      example: 01F3J0G1M4WQR6HGY6HCF6JA0K
    WebhookEvents:
      type: string
      enum:
        - INCOMING_FAX
        - FAX_COMPLETED
      x-enumDescriptions:
        INCOMING_FAX: A webhook event triggered by an fax is incoming.
        FAX_COMPLETED: A webhook event triggered by a fax that has successfully completed.
      description: The different events that can trigger a webhook
    GenericEvent:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/WebhookEvents'
        eventTime:
          description: Time of the event.
          type: string
          format: date-time
        fax:
          $ref: '#/components/schemas/Fax'
    ServiceId:
      x-PII: false
      x-v1: true
      readOnly: true
      type: string
      example: 01GVRB50KEQFFE1SGMPFRNBG6J
      description: ID of the fax service used.
    FaxStatus:
      type: string
      description: The status of the fax
      readOnly: true
      enum:
        - QUEUED
        - IN_PROGRESS
        - COMPLETED
        - FAILURE
      x-enumDescriptions:
        QUEUED: >-
          The operation is currently in a queue on a server and should be
          executed very soon.
        IN_PROGRESS: The fax is currently being sent (OUTBOUND) or received (INBOUND).
        COMPLETED: The fax operation succeeded. Everything went as normally planned.
        FAILURE: >-
          The fax operation failed. Details of the error can be found in the
          error_code field. For OUTBOUND fax, this means that NONE of the
          recipients received the fax.
    CoverPageData:
      type: object
      title: Cover page data
      description: >-
        You can use this to specify custom data for your cover page that will be
        sent as part of the fax. It is a key value store. Read more about how to
        use this
        [here](https://developers.sinch.com/docs/fax/api-reference/fax/cover-pages/).
        All keys used must be lower case.


        - `application/json` format: `"coverPageData":
        {"customfield1":"customdata1"}`

        - `multipart/form-data` format: `coverPageData[customfield1] =
        customdata1`
      additionalProperties:
        type: string
        x-additionalPropertiesName: coverPageKey
      example:
        toName: Acme Corp
    Labels:
      type: object
      title: label
      description: >-
        You can use this to attach labels to your call that you can use in your
        applications. It is a key value store.


        - `application/json` format: `"labels": {"label1":"value1"}`

        - `multipart/form-data` format: `labels[label1] = value1`
      additionalProperties:
        type: string
        x-additionalPropertiesName: labelKey
      example:
        use-case: fraudPrevention
        costCenter: sales
    PhoneNumber:
      x-PII: true
      x-v1: true
      type: string
      format: phoneNumber
      description: >-
        A phone number in
        [E.164](https://community.sinch.com/t5/Glossary/E-164/ta-p/7537) format,
        including the leading '+'.
      example: '+15551235656'
    ProjectId:
      type: string
      x-PII: false
      x-v1: false
      description: The `Id` of the project associated with the call.
      x-Internal: to support future account keys
      readOnly: true
      example: ae00f005-e392-44dc-b3f5-a657a2684dg3
    Money:
      description: >-
        This is where we need description to be overridden by `$ref:`
        description
      type: object
      readOnly: true
      properties:
        currencyCode:
          readOnly: true
          description: The 3-letter currency code defined in ISO 4217.
          type: string
          example: USD
        amount:
          readOnly: true
          description: The amount with 4 decimals and decimal delimiter `.`.
          type: string
          example: '0.0040'
    Resolution:
      type: string
      description: >-
        The resolution for the fax. If this is set at the service, this applies
        to all faxes sent using that service. If this is set on the fax, this
        will override the service setting.
      enum:
        - FINE
        - SUPERFINE
      x-enumDescriptions:
        FINE: Most commonly accepted fax resolution at 200 dpi.
        SUPERFINE: >-
          Higher but less commonly accepted fax resolution at 400 dpi. May be
          required when sending small text or detailed images.
    Pagination:
      type: object
      readOnly: true
      properties:
        page:
          readOnly: true
          type: integer
          description: Current page
        totalPages:
          readOnly: true
          type: integer
          description: Total number of pages.
        pageSize:
          readOnly: true
          type: integer
          description: Number of items per page.
        totalItems:
          type: integer
          readOnly: true
          format: int32
          description: Total size of the result.
    Error:
      type: object
      properties:
        code:
          description: HTTP status code or error code
          readOnly: true
          type: integer
          format: int32
          example: 400
        status:
          description: Response status name.
          readOnly: true
          type: string
          example: INVALID_ARGUMENT
        message:
          type: string
          readOnly: true
          description: A developer-facing error message
          example: Bad request.
        details:
          readOnly: true
          description: Details of the errors
          type: array
          items:
            type: object
            allOf:
              - $ref: '#/components/schemas/ErrorDetail'
    ErrorDetail:
      type: object
      anyOf:
        - $ref: '#/components/schemas/NotFoundDetail'
        - $ref: '#/components/schemas/BadRequestDetail'
        - $ref: '#/components/schemas/ErrorInfo'
      discriminator:
        propertyName: type
        mapping:
          NotFound: '#/components/schemas/NotFoundDetail'
          BadRequest: '#/components/schemas/BadRequestDetail'
          ErrorInfo: '#/components/schemas/ErrorInfo'
    ErrorType:
      readOnly: true
      description: Error type
      type: string
      enum:
        - DOCUMENT_CONVERSION_ERROR
        - CALL_ERROR
        - FAX_ERROR
        - FATAL_ERROR
        - GENERAL_ERROR
      x-enumDescriptions:
        DOCUMENT_CONVERSION_ERROR: A documentation conversion error.
        CALL_ERROR: A call error.
        FAX_ERROR: A fax error.
        FATAL_ERROR: A fatal error.
        GENERAL_ERROR: A general error.
    FaxErrors:
      type: object
      anyOf:
        - $ref: '#/components/schemas/DocumentConversionError'
        - $ref: '#/components/schemas/CallError'
        - $ref: '#/components/schemas/FaxError'
      discriminator:
        propertyName: errorType
        mapping:
          DOCUMENT_CONVERSION_ERROR: '#/components/schemas/DocumentConversionError'
          CALL_ERROR: '#/components/schemas/CallError'
          FAX_ERROR: '#/components/schemas/FaxError'
      examples:
        - DocumentConversionError: null
          summary: Document conversion error
          value:
            errorType: DOCUMENT_CONVERSION_ERROR
            errorMessage: >-
              There was a problem in converting and merging files to the output
              file format. Contact support.
            errorCode: 4
        - CallError: null
          summary: Call error
          value:
            errorType: CALL_ERROR
            errorMessage: Busy
            errorCode: 17
        - FaxError: null
          summary: Fax error
          value:
            errorType: FAX_ERROR
            errorMessage: Could not establish a connection to the fax server.
            errorCode: 6
    FaxError:
      type: object
      description: A problem occurred during the fax communication process.
      properties:
        errorType:
          description: Type of error for the fax
          type: string
          enum:
            - FAX_ERROR
          x-enumDescriptions:
            FAX_ERROR: An error related to the fax.
          example: FAX_ERROR
        errorMessage:
          description: A developer-facing error message
          type: string
          example: Could not establish a connection to the fax server.
        errorCode:
          type: integer
          description: The error code returned describing the error of the call
          enum:
            - 6
            - 7
            - 8
            - 10
            - 12
            - 13
            - 14
            - 18
            - 20
            - 21
            - 22
            - 25
            - 26
            - 28
            - 29
            - 31
            - 38
            - 40
            - 41
            - 44
            - 46
            - 48
            - 53
            - 60
            - 63
            - 68
            - 75
            - 76
            - 77
            - 79
            - 80
            - 82
            - 84
            - 113
            - 117
            - 119
            - 131
            - 132
            - 133
          x-enumDescriptions:
            '6': There was an error communicating with the far side.
            '7': Far end cannot receive at the size of image
            '8': No response after sending a page
            '10': Disconnected after permitted retries
            '12': Received no response to DCS or TCF
            '13': Timed out waiting for the first message
            '14': Timed out waiting for initial communication
            '18': Unexpected message received
            '20': The HDLC carrier did not stop in a timely manner
            '21': Received a DCN from remote after sending a page
            '22': Received bad response to DCS or training
            '25': Far end cannot receive at the resolution of the image
            '26': The remote fax machine failed to respond
            '28': Failed to train with any of the compatible modems
            '29': Invalid response after sending a page
            '31': Fax machine incompatibility
            '38': The remote fax machine hung up before receiving fax
            '40': Telephony error
            '41': Unexpected DCN while waiting for DCS or DIS
            '44': Telephony Error
            '46': >-
              Insufficient funds to send fax and not able to auto recharge;
              There was a problem charging your credit card. Please check your
              payment information and try again.
            '48': No answer (The Receiving Machine May Be Out Of Paper)
            '53': Unexpected DCN after EOM or MPS sequence
            '60': Transmission error after page break
            '63': Fax protocol error
            '68': Far end is not compatible
            '75': Manually canceled by user
            '76': Canceled automatically because timeout exceeded
            '77': Timed out waiting for receiver ready (ECM mode)
            '79': Can't cancel the fax, it's already complete!
            '80': Received a DCN while waiting for a DIS
            '82': There was an error communicating with the far side
            '84': Unexpected command after page received
            '113': The file for this fax has been deleted or is not accessible.
            '117': No pages received
            '119': User requested simulated faxError
            '131': Incomplete transmission
            '132': No fax tone detected
            '133': Phone number is not permitted
    CallError:
      type: object
      description: >-
        There was a problem with the phone line. The call could not be placed.
        Many times you can just try again
      properties:
        errorType:
          description: Type of error for the Call
          type: string
          enum:
            - CALL_ERROR
          x-enumDescriptions:
            CALL_ERROR: An error related to the call.
          example: CALL_ERROR
        errorMessage:
          description: A developer-facing error message
          type: string
          example: Busy
        errorCode:
          type: integer
          description: The error code returned describing the error of the call.
          enum:
            - 11
            - 15
            - 16
            - 17
            - 19
            - 30
            - 32
            - 34
            - 43
            - 49
          x-enumDescriptions:
            '11': The call dropped prematurely
            '15': Congestion
            '16': Ring Timeout
            '17': Busy
            '19': Immediate Hangup
            '30': No answer from a fax machine.
            '32': Incompatible destination
            '34': Phone number not operational
            '43': Problem establishing connection
            '49': The destination phone number Is Not active
    DocumentConversionError:
      type: object
      description: >-
        Conversion errors usually occur when there is a problem with one of the
        files you posted.
      properties:
        errorType:
          description: Type of error for the Document conversion
          type: string
          enum:
            - DOCUMENT_CONVERSION_ERROR
          x-enumDescriptions:
            DOCUMENT_CONVERSION_ERROR: An error related to document conversion.
          example: DOCUMENT_CONVERSION_ERROR
        errorMessage:
          description: The error message
          type: string
          example: >-
            There was a problem in converting and merging files to the output
            file format. Contact support.
        errorCode:
          type: integer
          description: The error code returned during document conversion.
          enum:
            - 4
            - 54
            - 55
            - 57
            - 69
            - 122
            - 128
            - 129
            - 130
            - 133
          x-enumDescriptions:
            '4': >-
              There was a problem in converting and merging files to the output
              file format. Contact support.
            '54': Could not access the url you provided. {contentUrl}
            '55': The string_data URL you provided is invalid
            '57': There was a problem storing the file you provided.
            '69': There was a problem storing the file you provided.
            '122': User simulated Document Conversion Error
            '128': Could not determine mimetype for file.
            '129': Mimetype not supported.
            '130': 'Mimetype not supported: application/xml'
            '133': Failed to normalize PDF document
    NotFoundDetail:
      type: object
      description: The request was malformed on one or more fields.
      x-internal: >-
        https://github.com/googleapis/googleapis/blob/f79d6e85a9a6b913a5e9cb0067e846e7f087dbc8/google/rpc/error_details.proto#L169
      properties:
        type:
          type: string
          description: The request was malformed on one or more properties.
          readOnly: true
          example: NOT_FOUND
          default: BadRequest
    BadRequestDetail:
      type: object
      description: The request was malformed on one or more fields.
      x-internal: >-
        https://github.com/googleapis/googleapis/blob/f79d6e85a9a6b913a5e9cb0067e846e7f087dbc8/google/rpc/error_details.proto#L169
      properties:
        type:
          type: string
          description: The request was malformed on one or more properties.
          readOnly: true
          example: BadRequest
          default: BadRequest
        fieldViolations:
          description: The field violation(s).
          type: array
          items:
            type: object
            readOnly: true
            allOf:
              - $ref: '#/components/schemas/FieldViolation'
          example:
            - field: to
              description: Phone number was not in the expected format.
    FieldViolation:
      type: object
      properties:
        field:
          type: string
          readOnly: true
          description: Request field.
          example: to
        description:
          type: string
          readOnly: true
          description: Description of why the request field was considered invalid.
          example: Phone number was not in the expected format.
    ErrorInfo:
      description: |-
        Describes the cause of the error with structured details.
        Example of an error when trying to make a call to blocked destination:

             { "reason": "DESTINATION_BLOCKED"
               "domain": "VOICE"
               "metadata": {
                 "country": "Bermuda",
               }
             }
      type: object
      properties:
        type:
          type: string
          description: >-
            Describes the cause of the error with structured details.

            Example of an error when trying to make a call to blocked
            destination:


            ```
                { "reason": "DESTINATION_BLOCKED"
                  "domain": "VOICE"
                  "metadata": {
                    "country": "Bermuda",
                  }
                }
            ```
          default: ErrorInfo
          example: ErrorInfo
        reason:
          type: string
          description: >-
            The reason of the error. This is a constant value that identifies
            the

            proximate cause of the error. Error reasons are unique. Max 63
            characters and match
             /[A-Z0-9_]+/.
          maxLength: 63
        domain:
          type: string
          description: Domain for error, for voice its always sinch.voice
        metaData:
          description: >-
            Additional structured details about this error. key value pair of
            strings
          type: object
  parameters:
    Id:
      in: path
      name: id
      required: true
      description: The ID of the fax.
      schema:
        $ref: '#/components/schemas/FaxId'
    Page:
      in: query
      name: page
      description: >-
        The page you want to retrieve returned from a previous List request, if
        any
      schema:
        type: string
    PageSize:
      name: pageSize
      in: query
      description: >-
        The maximum number of items to return per request. The default is 100
        and the maximum is 1000. If you need to export larger amounts and
        pagination is not suitable for you can use the Export function in the
        dashboard.
      schema:
        type: integer
        maximum: 1000
        minimum: 1
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        The user name and password is your keyId and key secret from the [Access
        keys sections](https://dashboard.sinch.com/settings/access-keys)
    OAuth2:
      type: oauth2
      description: >-
        The user name and password is your key id and key secret from the
        [Access keys sections](https://dashboard.sinch.com/settings/access-keys)
      flows:
        clientCredentials:
          tokenUrl: https://auth.sinch.com/oauth2/token
          scopes: {}
