Choosing an Interface

Concord offers developers and integrators a number of ways to tie their applications in with Outbound Fax Delivery Services, through interfaces. By offering several interfaces, Concord’s Outbound Fax Delivery Services provide the ultimate flexibility for integrators to decide which method best meets the requirements of their applications and the skill sets of their development resources.

Each of the interfaces allow for external applications to submit fax delivery requests to Concord’s platform for delivery. Notification on delivery completion is also provided. In addition to these basic features, each interface has extra benefits in particular areas, be it simplicity of use, or range of more advanced features. For that reason, reviewing the available interface options and choosing the interface that is right for you can make a big difference in the success and effort involved in your integration project.

The available interfaces for Outbound Fax Delivery Services are listed in the table below:

Name	Description
Fax Web Service Interface	Receives fax submission requests via Web Services and SOAP. Requests can be submitted from any application capable of calling Web Service methods. The fax job request is created programmatically, with the addition of recipients, files to deliver and delivery instructions (such as time to start delivery). Acknowledgment of the submission is immediate, with a unique job identifier returned. Features include the ability to obtain fax delivery status information in real-time for any previously submitted fax job request, using the identifier returned from the job submission. Notifications of delivery completion can be requested as part of the job submission. If requested, the notification messages sent either via the Push Notification Interface or SMTP Interface. Other features include the ability to request the cancellation of a fax job in progress.
SMTP Interface	Receives fax submission requests via SMTP email messages. Submission requests can be submitted from any email client, or custom application capable of generating email messages. Fax destinations are supplied via recipients in the To: line, a special format is used to denote the destination (e.g. 12065551212@concordsend.com for fax delivery to destination +1 206 555-1212). Files attached to the submitted email messages are sent as part of the delivered fax. Notification messages are sent back to the submitter (identified via submitting email address), any may include copies of the received or delivered documents.
Push Notification Interface	Used to send notification information back to client applications regarding the status of submitted fax delivery requests. This interface does not support submission features. This interface supports many protocols, including HTTP POST and HTTP GET.

Name

Description

Fax Web Service Interface

Receives fax submission requests via Web Services and SOAP. Requests can be submitted from any application capable of calling Web Service methods.

The fax job request is created programmatically, with the addition of recipients, files to deliver and delivery instructions (such as time to start delivery). Acknowledgment of the submission is immediate, with a unique job identifier returned.

Features include the ability to obtain fax delivery status information in real-time for any previously submitted fax job request, using the identifier returned from the job submission.

Notifications of delivery completion can be requested as part of the job submission. If requested, the notification messages sent either via the Push Notification Interface or SMTP Interface.

Other features include the ability to request the cancellation of a fax job in progress.

SMTP Interface

Receives fax submission requests via SMTP email messages. Submission requests can be submitted from any email client, or custom application capable of generating email messages.

Fax destinations are supplied via recipients in the To: line, a special format is used to denote the destination (e.g. 12065551212@concordsend.com for fax delivery to destination +1 206 555-1212). Files attached to the submitted email messages are sent as part of the delivered fax.

Notification messages are sent back to the submitter (identified via submitting email address), any may include copies of the received or delivered documents.

Push Notification Interface

Used to send notification information back to client applications regarding the status of submitted fax delivery requests. This interface does not support submission features.

This interface supports many protocols, including HTTP POST and HTTP GET.

Factors for Consideration

Choosing which interface to use is an important part of the development process, and due care should be taken when evaluating the needs of your applications against the capabilities of each of the interfaces.

Factors to consider when deciding which interface to use should include:

Simplicity
- Applications are designed as solutions to business problems. The scope and complexity of the business problem should drive the size and complexity of the solution. If the problem is simple and small in scope (e.g. a small business or department wishes to do away with fax machines in the office) then that may tend towards a simple solution (e.g. allow users to send and receive faxes from their desktops using their existing email application).
  A more complex business problem, such as a production fax integration with other applications within the organization, or a solution where secure transfer of sensitive information is required, may point to use of the Fax Web Services Interface, where transmittal of fax requests are performed using a secure protocol. As a developer, you will need to decide how much development effort your solution is worthy of, while making sure that your solution meets the needs of the original business problem.

Development Availability and Expertise
- The skill set of the developers and integrators working on a project will affect the technologies you can employ to use Concord’s Outbound Fax Delivery Services, and the interfaces that you can tie in to your application. Some of the interfaces on offer are very simple to use. For example, submitting requests through the SMTP Interface can be as simple as composing an email message and submitting it to a specific email address! There are several components and libraries available that make the creation and send of an email message from a custom application a trivial task.
  For developers with more familiarity with Web Services and SOAP, use of the Fax Web Services Interface may be a more appealing option. An immediate response from Concord’s platform (to confirm that a submitted fax request has been accepted or rejected) and the ability to poll for the real-time fax delivery status of submitted requests are all available features within the Fax Web Services interface. Generally though, coding to this interface requires greater development expertise as more integration code would be needed than if using other interfaces.

Range of Features
- Not all interfaces within Concord’s Outbound Fax Delivery Services offer the same features. While core features like fax submission and notification of delivery completion are built into each interface, there are features that are better represented in one interface over another.
  Even within a specific interface, there may be more than one method available to use a particular feature. An example of this is the fact that the Fax Web Services Interface offers more than one Web Method for submitting a fax request, offering less or more control over the submission parameters for your request. You will need to decide which of the features sets best meets the needs of your solution, and which of the methods within an interface you will choose to integrate into your application.

Tightness of Integration
- Your application may or may not need to track a fax submission request once it has been submitted to Concord’s Outbound Fax Delivery Services. Logs on submission and delivery times, information on delivery success and failure, and the need to receive and store this information without the need for operator intervention may indicate a tight integration between your application and Concord’s Outbound Fax Delivery Services.
  The SMTP interface, by virtue of the SMTP protocol, is inherently disconnected. Between your application (either custom or a standard email client) there are many layers that an email message will travel through before it reaches its destination. Each of these layers ‘hands off’ the email message to the next, so that when the message finally is received by Concord’s Outbound Fax Delivery Services, it has passed through many hands, and the original submitter is no longer in control of the message. As a result of this, the SMTP notification message that comes back to confirm receipt of the fax submission is also disconnected, meaning that it may take some time after submission before you receive the submission notification message. It also means that it is up to your application (or the users of your application) to tie the notification messages back to the original submission. The same requirements apply to the final delivery confirmation message, which also comes back as a SMTP message.
  On the other hand, if you are using an interface like Fax Web Services for submission, your submission is immediately confirmed or rejected as part of the submission conversation between your application and Concord’s Outbound Fax Delivery Services. The interface returns a unique identifier that can be used to proactively track the fax delivery status of that submission in real-time, until it is completed. This allows for a very tight integration into your solution, as it possible to directly associate the submitted fax request with your application’s business entities as part of the fax submission operation.

Available Infrastructure Within Your Organization
- Use of the interfaces available within Concord’s Outbound Fax Delivery Services is influenced by the infrastructure you have in place, or are willing to put in place, to implement your solution.
  The most basic use of the SMTP interface requires nothing more than the ability to send and receive email messages, possibly with attachments. The infrastructure required to support these features is available in just about every organization already, as this is exactly the same infrastructure required to allow employees to send and receive email.
  On the other hand, Push Notification interfaces, such as HTTP GET, require that the receiving organization is capable of receiving and processing HTTP requests. This typically means hosting a Web server, with a resolvable URL that can be accessed from the public Internet. Allowing access to your servers from the outside world in a safe way typically means the use of firewalls to create a DMZ where your servers will reside. Networking expertise may be required in order to achieve this network setup.

Security

Security plays a greater and greater role in solutions that interact with hosted service providers, such as Concord, or any other third party. Whether needing to comply with government legislation (such as HIPAA), company codes of conduct or client requirements the protection of sensitive customer information should always be a factor when implementing a solution to a business problem. This protection extends to the transmittal of information between the application and third party providers. Concord’s Outbound Fax Delivery Services allow your security requirements to be met while allowing performing fax functions.

The Fax Web Services interface is designed around SOAP, using the HTTPS protocol and SSL. These are the industry standard secure protocols used by web sites on the Internet when securing communication between clients and servers. As communication with Concord over Fax Web Services interface is all over HTTPS, it is not possible to transmit fax submission requests (or call any other Web Method) in an unencrypted fashion.

Push Notification interfaces, such as HTTP GET, will honor the protocol specified by your application when submitting the fax request. To this end, the protocol used to return the notification may be secured (HTTPS) or unsecured (HTTP). In this case, it is up to you to make ensure your application requests secure notifications and that your infrastructure is set up to support secure communications.

Note
The SMTP interface, by default, is not secure. However, it is possible to require that all email communications between your organization and Concord via the SMTP Interface, are secured using TLS (Transport Level Security). This requires your organization to configure their mail servers; something your email administrator would be responsible for doing.

Interface Selection Hints

The following section is a brief summary of the key features that your application may have, and the interface or interfaces best suited to meet the needs of those features. Note that this is intended as a guide to which interface may be best suited for your needs. You should always consider reviewing the detailed documentation for each of the available interfaces to see if the additional information available indicates one interface over another.

If you want to...	Consider using...
Submit a fax request using an existing email client.	SMTP Interface
Avoid creating custom code for end users to submit fax requests and receive delivery confirmations.	SMTP Interface
Submit a fax request and schedule it for later delivery.	Submit an Extended Fax using the Fax Web Service Interface.
Cancel a fax job after it has been submitted.	Cancel a Fax using the Fax Web Service Interface.
Get instant acceptance of a submitted fax request.	Submit a Simple or Extended Fax using the Fax Web Service Interface.
Know why a submitted fax request was rejected.	Review the results of a Simple or Extended Fax submission using the Fax Web Service Interface. Await the response notification message indicating that your submission was not accepted using the SMTP Interface.
Get real-time fax delivery status of a submitted fax job, when you ask for it.	Request the current fax delivery status, in basic or extended format, of a previously submitted fax job using the Fax Web Service Interface.
Be informed when a fax has been delivered, without having to ask for the status.	Request a notification via the SMTP Interface or the Push Notification Interface when submitting a Simple or Extended Fax using the Fax Web Service Interface. Await the delivery completion notification message, indicating that your fax has been successfully delivered, using the SMTP Interface.
Know how many pages of a fax have been delivered.	Request the current fax delivery status of a previously submitted fax job using the Fax Web Service Interface. Review the returned data to get the current page count.
Know why a fax was not delivered.	Request the current fax delivery status of a previously submitted fax job using the Fax Web Services Interface. Review the returned data to obtain reason for delivery failure. Request a notification via the Push Notification Interface when submitting a Simple or Extended Fax using the Fax Web Services Interface. Review the supplied data to retrieve the reason for delivery failure. Await the delivery completion notification message, indicating that your fax has not been delivered, via the SMTP Interface. Review the returned message to obtain reason for delivery failure.
Submit the same document to go to multiple recipients.	Include several recipients in your "To" list when submitting message using the SMTP Interface. Add several recipients to your submission record when submitting a Simple or Extended Fax using the Fax Web Services Interface.
Use my email client’s contact manager to store and retrieve fax numbers for contacts.	Store contact fax numbers as email addresses within contact manager. Add these contacts as recipients when submitting message using the SMTP Interface.
Ensure that fax submissions are transmitted to Concord in a secured manner.	Submit a Simple or Extended Fax using the Fax Web Services Interface.
Receive notifications of fax delivery completion in a secured manner.	Request the current fax delivery status of a previously submitted fax job using the Fax Web Services Interface. Request a notification via the Push Notification Interface when submitting a Simple or Extended Fax using the Fax Web Services Interface. Ensure that you supply a URL using the https:// secured protocol.
Submit a fax request containing multiple files to deliver.	Attach multiple documents to an email message when submitting using the STMP Interface. Add multiple FaxFile objects to the submission when submitting a Simple or Extended Fax using the Fax Web Services Interface.
Receive copies of the documents that are faxed, upon delivery completion.	If your account with Concord is configured to return delivered documents upon delivery success (or failure) and submit via the SMTP Interface, you will automatically receive a copy of the faxed documents as attachments to the notification messages. Set the value of NotifyIncludeDeliveredImage in JobDetails when submitting an Extended Fax using the Fax Web Services Interface.
Include a cover page with the fax job submission.	If your account with Concord is configured to include a cover page then that setting is honored for all submissions, regardless of the interface used.

For a detailed comparison of the features available in each interface see the help article xxxxx.

Using Multiple Interfaces

While this article has discussed so far how to choose a single interface for your application, there is nothing that stops you from using multiple interfaces in your solution, if that is what you decide. Regardless of the interface you choose, the fax submitted by your application are sent to the same platform and delivered using the same method. Therefore, if you should decide that your application requires, for example, some faxes submitted via the SMTP Interface and some submitted via the Fax Web Services Interface, that is a perfectly valid solution.

If you decide to proceed with this kind of integration, be aware of the features and limitations of each of the interfaces. Review the detailed documentation on each of the interfaces and make sure that the use of the interfaces meets the needs of your application.

See Also

Other Resources