Aizan

/tokens

/health

/faxes/received

/faxes/sent

/faxes/metadata

/faxes

/faxes/{fax_id}/metadata

/faxes/{fax_id}/image

/faxes/{fax_id}/image/pages

/faxes/{fax_id}

/faxes/{fax_id}/cancel

/faxes/{fax_id}/transmission-details

/applications/{application-id}/notifications

/applications/{application-id}/notifications/{notification-id}

/notifications

/reports/usage

/reports/usage/download/{report-key}

Default

Mainstay Fax API

Development

Sandbox

Mapped to AWS Cognito&apos;s /oauth2/token that allows users to request access tokens for authenticating and authorizing client applications.

Mapped to AWS Cognito's /oauth2/token that allows users to request access tokens for authenticating and authorizing client applications.

Specifies the type of authorization grant requested, which is required for the OAuth2 token endpoint.

grant_type

Defines the scope of the access request, specifying the resources the token can access.

scope

Contains the credentials used to authenticate the client making the request for authorization purposes.

Authorization

access_token

expires_in

token_type

Allows to check the current health status of the service.

Allows to check the current health status of the service.

The authorization token for accessing the API.

status

{
 "errors": [
 {
 "element_name": "<element>",
 "user_message": "<user message>",
 "developer_message": "<more details for dev>",
 "more_info": "",
 "error_code": "100"
 }
 ],
 "transaction_id": TRANSACTION_ID
}

The /faxes/received section allows users to retrieve a list of faxes that have been received by the user. Users can access details such as fax-id, size, duration, pages, and timestamps related to the received faxes, facilitating efficient management and tracking of incoming fax communications. This section helps users conveniently access and review their received faxes within the application.

The /faxes/received section allows users to retrieve a list of faxes that have been received by the user. Users can access details such as fax-id, size, duration, pages, and timestamps related to the received faxes, facilitating efficient management and tracking of incoming fax communications. This section helps users conveniently access and review their received faxes within the application.

The unique identifier of the user making the API call.

user-id

The transaction ID for tracking the API call.

transaction-id

The pagination-limit parameter specifies the maximum number of received faxes to return in a single API response. This parameter helps control the amount of data retrieved at once, aiding in query optimization and performance.

pagination-limit

The pagination-offset parameter determines the starting point for fetching received faxes in the API response. By setting this parameter, users can navigate through the result set efficiently, fetching data from a specific position in the list of received faxes.

pagination-offset

first_record

last_record

faxes

{
 "errors": [
 {
 "element_name": "<element>",
 "user_message": "<user message>",
 "developer_message": "<more details for dev>",
 "more_info": "",
 "error_code": "100"
 }
 ],
 "transaction_id": TRANSACTION_ID
}

The /faxes/sent section allows users to retrieve information on faxes that have been successfully sent. Users can access details such as fax-id, size, duration, pages, and transmission status to track the status and details of their sent faxes. This section provides a comprehensive overview of all successfully sent faxes for user reference and tracking purposes.

The /faxes/sent section allows users to retrieve information on faxes that have been successfully sent. Users can access details such as fax-id, size, duration, pages, and transmission status to track the status and details of their sent faxes. This section provides a comprehensive overview of all successfully sent faxes for user reference and tracking purposes.

The maximum number of sent faxes to be returned in a single API call.

Specifies the starting point from which to retrieve sent faxes in the result set.

Filters the sent faxes based on their transmission status, such as "success" or "failed".

transmission_status

The /faxes/metadata section allows users to retrieve a list of metadata associated with specified fax-ids. By utilizing this API endpoint, users can access additional information such as fax size, duration, page count, and status for specific faxes, enabling them to manage and track fax transmissions efficiently.

The /faxes/metadata section allows users to retrieve a list of metadata associated with specified fax-ids. By utilizing this API endpoint, users can access additional information such as fax size, duration, page count, and status for specific faxes, enabling them to manage and track fax transmissions efficiently.

The fax_ids body parameter is a list of unique identifiers for the faxes that the user wants to retrieve metadata for. This parameter allows for the selection of specific faxes to retrieve additional information about.

fax_ids

The /faxes section allows users to send fax transmissions with customizable options, such as resolution settings, cover page inclusion, and billing details. Users can specify recipient information, document types, and additional client data to facilitate the fax transmission process. The section returns a unique fax-id and destination fax number upon successful submission.

The /faxes section allows users to send fax transmissions with customizable options, such as resolution settings, cover page inclusion, and billing details. Users can specify recipient information, document types, and additional client data to facilitate the fax transmission process. The section returns a unique fax-id and destination fax number upon successful submission.

The list of destination numbers for the fax.

destinations

Additional options related to the fax transmission, such as priority or scheduling.

fax_options

client_data

documents

This section provides detailed information about a specific fax, including size, duration, pages, status, and more. Users can retrieve comprehensive metadata about a fax transmission, enabling them to track and manage fax communications effectively within their application.

This section provides detailed information about a specific fax, including size, duration, pages, status, and more. Users can retrieve comprehensive metadata about a fax transmission, enabling them to track and manage fax communications effectively within their application.

fax_id

size

duration

pages

image_downloaded

fax_status

completed_timestamp

direction

originating_fax_number

destination_fax_number

originating_fax_tsid

destination_fax_csid

routing_data

transmission_data

client_tracking_data

This section allows users to update and retrieve detailed metadata for a specific fax transmission. This call allows the end user to edit limited information on a SINGLE fax image (either sent or received) from a metadata list obtained in a previous “listing” query. The only available metadata field for editing is &quot;image_downloaded&quot;.
<h2 class="slate-h2 " ><a href="https://consensus.stoplight.io/docs/fax-services/e1218c9484f00-edit-a-fax-s-metadata#what-you-must-pass-in" target="_blank">
</a></h2>

This section allows users to update and retrieve detailed metadata for a specific fax transmission. This call allows the end user to edit limited information on a SINGLE fax image (either sent or received) from a metadata list obtained in a previous “listing” query.  

The only available metadata field for editing is "image_downloaded".

The unique identifier of the user initiating the API call.

A unique identifier for tracking the API call.

The authorization token required for accessing the API.

Content-Type

Indicates whether the fax image has been downloaded.

The timestamp indicating when the fax transmission was completed.

The direction of the fax transmission (e.g., inbound or outbound).

The phone number of the originating fax machine.

The phone number of the destination fax machine.

The transmission service identifier of the originating fax.

The CSID (Caller Station Identification) of the destination fax machine.

Data related to the routing of the fax transmission.

Additional data related to the fax transmission.

Additional tracking data provided by the client for the fax.

This section allows users to retrieve the image associated with a specific fax-id. By accessing this endpoint, users can view and download the image file, along with relevant metadata such as the file name. This functionality enables seamless integration of fax image retrieval into various applications and workflows.

This section allows users to retrieve the image associated with a specific fax-id. By accessing this endpoint, users can view and download the image file, along with relevant metadata such as the file name. This functionality enables seamless integration of fax image retrieval into various applications and workflows.

The fax_id path parameter specifies the unique identifier of the fax image to retrieve.

desired_fromat

This response parameter represents the name of the file associated with the requested image.

file_name

The response parameter image represents the image data retrieved from the specified fax ID.

image

{
    "errors": [
        {
            "element_name": "image_fax",
            "user_message": "Cannot get fax image",
            "developer_message": "Cannot retrieve fax tiff for fax_id: a3f3e7d2-...",
            "more_info": "",
            "error_code": "102"
        }
    ],
    "transaction_id": TRANSACTION_ID
}

This section allows users to retrieve specific pages of a fax image by providing the fax-id and specifying the starting page number and the number of pages to retrieve. Users can access individual pages of a fax image for viewing or processing purposes through this API section.

This section allows users to retrieve specific pages of a fax image by providing the fax-id and specifying the starting page number and the number of pages to retrieve. Users can access individual pages of a fax image for viewing or processing purposes through this API section.

The start_page query parameter indicates the starting page number for retrieving fax images from the specified fax.

start_page

The num_pages query parameter specifies the number of pages to be returned in the response for the fax image retrieval.

num_pages

This request allows users to delete a specific fax by its fax-id.

This request allows users to delete a specific fax by its fax-id.

message

This request allows users to cancel a specific fax by its fax-id.

This request allows users to cancel a specific fax by its fax-id.

This section provides detailed transmission information for a specific fax, including status, timestamps, error codes, and retry data. Users can retrieve comprehensive details about the transmission process to track the progress and troubleshoot any issues effectively.

This section provides detailed transmission information for a specific fax, including status, timestamps, error codes, and retry data. Users can retrieve comprehensive details about the transmission process to track the progress and troubleshoot any issues effectively.

attempts

This section allows users to retrieve notifications associated with a specific application.

This section allows users to retrieve notifications associated with a specific application.

The identifier for the admin user associated with the application.

The password for the admin user accessing the notifications.

user_id

The identifier for the transaction related to the notification.

The unique identifier for the application to retrieve specific notifications.

application-id

This section allows users to send notifications within a specific application, specifying details such as notification direction, type, destination, and HMAC secret for message integrity verification.

This section allows users to send notifications within a specific application, specifying details such as notification direction, type, destination, and HMAC secret for message integrity verification.

Specifies the direction of the notification, either incoming or outgoing.

The type of notification being sent, such as email, SMS, or push notification.

type

The destination where the notification will be sent.

notify_destination

A secret key used for message integrity verification using HMAC.

hmac_secret

The unique identifier for the admin user responsible for the notification.

The password associated with the admin account for authentication purposes.

The unique identifier for the transaction associated with the notification.

The unique identifier for the application where the notification is being sent.

This section allows users to delete a specific notification associated with an application.

This section allows users to delete a specific notification associated with an application.

The unique identifier of the administrator associated with the notification being deleted.

The username of the administrator making the request to delete the notification.

The transaction identifier associated with the deletion request.

The unique identifier of the application to which the notification belongs.

The unique identifier of the notification to be deleted.

notification-id

This section allows users to update specific notifications associated with a particular application.

This section allows users to update specific notifications associated with a particular application.

The destination to be notified when the action is triggered.

The secret key used for Hash-based Message Authentication Code (HMAC) for secure communication.

The unique identifier of the admin user making the request.

The password of the admin user making the request.

The unique identifier of the transaction associated with the notification.

The unique identifier of the notification to be updated.

The /notifications section provides users with the ability to retrieve detailed information about specific transactions, including timestamp, fax direction, and sent status. By utilizing various parameters, users can efficiently access transmission details for their transactions without the need for manual data extraction. This section streamlines the process of retrieving transaction information, enhancing efficiency and facilitating seamless integration with other systems.

The /notifications section provides users with the ability to retrieve detailed information about specific transactions, including timestamp, fax direction, and sent status. By utilizing various parameters, users can efficiently access transmission details for their transactions without the need for manual data extraction. This section streamlines the process of retrieving transaction information, enhancing efficiency and facilitating seamless integration with other systems.

A header parameter uniquely identifying a specific transaction related to the notifications.

transaction_id

A header parameter used for authenticating the request and granting access to the notifications endpoint.

A header parameter indicating the maximum number of notifications to be returned in a single paginated response.

A header parameter used for pagination, indicating the starting point from which notifications should be retrieved.

pagination-offset-id

A query parameter specifying a timestamp to filter notifications that occurred after the specified time.

after

A query parameter specifying a timestamp to filter notifications that occurred before the specified time.

before

A query parameter defining the direction of the fax notification.

fax_direction

A query parameter used to filter notifications based on the status of their delivery.

sent_status

The /reports/usage section provides authenticated administrators with a list of usage reports based on specified query parameters. Users can retrieve download URLs for various reports by setting parameters such as report period, service type, start date, and end date, enabling them to programmatically access and download the necessary reports as needed.Returns a list of usage reports according to the query parameters reportPeriod, serviceType, startDate and endDate, providing the download URL of each report, for the authenticated administrator.Using this endpoint response, the client can programmatically get and download the set of reports he needs by selecting the appropriate query parameters and then iterating through the response records downloading the ones he needs using the URLs as-is.

The /reports/usage section provides authenticated administrators with a list of usage reports based on specified query parameters. Users can retrieve download URLs for various reports by setting parameters such as report period, service type, start date, and end date, enabling them to programmatically access and download the necessary reports as needed.

The unique ID of the admin user accessing the reports.

admin-id

The password of the admin user accessing the reports.

admin-password

The username of the admin user accessing the reports.

admin-username

The unique transaction ID associated with the report.

The end date for the report data to be retrieved. Format should be in YYYY-MM-DD.

endDate

The period for which the report data should be generated (e.g. daily, weekly, monthly).

reportPeriod

The type of service for which the report data is being requested.

serviceType

The start date for the report data to be retrieved. Format should be in YYYY-MM-DD.

startDate

This section enables users to download usage reports by providing a unique report key. Users can retrieve detailed usage data in various file formats to analyze and track their consumption patterns efficiently. This feature streamlines the process of accessing and managing critical usage information for better decision-making.

This section enables users to download usage reports by providing a unique report key. Users can retrieve detailed usage data in various file formats to analyze and track their consumption patterns efficiently. This feature streamlines the process of accessing and managing critical usage information for better decision-making.

The ID of the admin user making the request for the report download.

The password of the admin user authenticating the request for the report download.

Sections