As I’ve mentioned many times, we try to keep Phaxio as simple and straightforward as possible. I’ve been looking around the interwebs at some other great APIs and I think it may also be beneficial to have primer available for developers looking to get the most out of the send fax operation.If you’re reading this primer, you won’t be learning any coding tricks, you’ll simply understand why certain parameters exist and how to use them to your benefit. 

The send fax docs are a pretty good place to get started and it may help to keep a tab open while you’re reading this primer.

Building Your Application

Let’s imagine that you’re building a restaurant ordering application and you’re going to use Phaxio to send the orders to restaurants.

Phaxio gives you the ability to send faxes by either sending a file (PDF, docs etc.), HTML, URL, or a text string. While sending a PDF might seem standard, passing us urls has a significant advantage in that you don’t need to worry about rendering the document yourself.

Now we have all of the necessary pieces in place to send our very first fax. 

curl <a href="https://api.phaxio.com/v1/send">https://api.phaxio.com/v1/send</a> \
            -F 'to=55555555555' \
            -F 'string_data=http://myrestaurantapp.com/....' \
            -F 'string_data_type=URL' \
            -F 'API_key=API_KEY' \
            -F 'API_secret=API_SECRET'

Batching & Collision Avoidance

It’s important to remember that a fax machine can only receive one call at a time. Making multiple calls to the fax machine too close together will probably cause your faxes to fail. Our batching feature uses a delay to collect multiple faxes to a single location and send them in a single call. The collision avoidance makes sure that no two batches to a single number are sent at the same time. If you’re building a restaurant app, make sure that batching and collision avoidance are turned on!

Now our call looks like this: 

curl <a href="https://api.phaxio.com/v1/send">https://api.phaxio.com/v1/send</a> \
            -F 'to=55555555555' \
            -F 'filename=http://myrestaurantapp.com' \
            -F 'batch=true' \
            -F 'batch_delay=45' \
            -F 'batch_collision_avoidance=true' \
            -F 'API_key=API_KEY' \
            -F 'API_secret=API_SECRET'

Dynamic Callback URLs

Many of our clients use our callbacks to trigger a call to the receiving restaurant to confirm that they are working on the order. To do this you’ll probably want to dynamically create a URL so that your application can track each order separately. 

This can all be accomplished through the API by including the “callback_URL” parameter within your call. 

        curl <a href="https://api.phaxio.com/v1/send">https://api.phaxio.com/v1/send</a> \
            -F 'to=55555555555' \
            -F 'filename=http://myrestaurantapp.com' \
            -F 'batch=true' \
            -F 'batch_delay=45' \
            -F 'batch_collision_avoidance=true' \
            -F 'callback_URL=http://myrestaurantapp.com/callbacks/faxes/sent?                       type=orders&amp;id=24' \
            -F 'API_key=API_KEY' \
            -F 'API_secret=API_SECRET'

Now I can use that callback (and id) within my application to create a confirmation phone call!

Cancel Timeouts

Cancel Timeout can be incredibly helpful for restaurant ordering applications. Simply said, you can set a timeout period for your faxes. If a fax hasn’t finished by the end of the timeout period Phaxio will kill the fax and respond with a failure. Obviously the timeout period should be no less than a couple of minutes for a one page fax. Also,** make sure to take your batch delay into account when setting your cancel timeout**. 

Now our call might look something like this:

curl <a href="https://api.phaxio.com/v1/send">https://api.phaxio.com/v1/send</a> \
            -F 'to=55555555555' \
            -F 'filename=http://myrestaurantapp.com' \
            -F 'batch=true' \
            -F 'batch_delay=45' \
            -F 'batch_collision_avoidance=true' \
            -F 'callback_URL=http://myrestaurantapp.com/callbacks/faxes/sent?                       type=orders&amp;id=24' \
            -F 'cancel_timeout=15' \
            -F 'API_key=API_KEY' \
            -F 'API_secret=API_SECRET' 

And that’s pretty much it. Have any questions of comments? Leave ‘em in the comments.