We demo using Advanced Rest Services Client for Google Chrome.  There is a bug in Google Chrome 56-58 where any file attachment on an outgoing fax shows a content-length of 0 bytes. If this happens to you, download Google Chrome Version 55.

Sending Fax and Attachments with Web Services API

Alright, so we’re going to walk through sending a fax through the RightFax web API with an attachment today.

So we’re on a server named HQRF, so you’re gonna see me use that in our URLs. So the first thing I need to do is I need to authenticate to my API. Now, we authenticate to the web API via basic authentication. You can see I’ve got some pre-filled URLs in here. So I’m going to start off by just doing a simple get request to the root of the API, which is the rightfax/api directory on my server.

Now, when I do this, it’s going to ask me for authentication. I’m just using in my built-in administrator account, with no password. You do want to use a RightFax account that is not in active directory. We pass in a basic authorization header, most of your programming systems can pre-generate those.

What this base request does, if you do just get the base of the API folder using your credentials, is it’s going to return the basic information about the API. It’s going to tell you your version number, your build number, who you’re logged in as, and whether it’s a RightFax or a Windows account.

Again, Windows-linked accounts are a little more problematic, there’s a lot more configuration to make those work.

It’s also going to give you some links to your account and your user. It’s going to give you some links to allow you to go look up all of the documents for this user, to go look up all of the send jobs for this user.

This kind of route request gives you links to go look up a tremendous amount of information about the user that you’re logged in as.

We use this primarily just to make sure that we’re authenticated correctly, and that we can see what our username is.

So at this point, we’re authenticated. This is also generated (my authorization header). In the advanced rest client, once you’ve generated this once, it’s going to stay in there as you modify your request, so that you don’t have to re-enter your credentials every time.

In order to send a fax, the next thing I need to do is I need to upload my fax body. Whatever type of file I’m using, I need to upload that.

So I’m going to change this to be a post request. I’m going to upload this to our attachments endpoint, which you can see I also have in there.

For the body of my request I’m going to go over to files. Tell it to add a file, choose that file, and grab a file from there.

You can see it’s automatically going to add a content type header, so I don’t need to worry about changing my headers here. So I’m just going to hit send.

Now, this is where things get interesting. By default in advanced rest client, these details down here are hidden. So all you’re going see is we got a created response, but the response was empty.

The server actually returns you the information you need from this post request as a header, so I need to hit details to open that up. Go into my response headers, and from there it gives me this location header. This contains the URL of the file I just uploaded. So I’m actually going to take that URL, and I’m going to use it in my next request.

Then the final request that I’m going to make here to actually send this is I’m going to go over to our send jobs endpoint. I’m going to do a post. I’m going to remove that file and do a raw payload, and I’m going to post in the JSON object.

So this is JSON object that contains a lot of the parameters of send job. This is the most basic set of parameters that we use for testing. This is the one recipient with a name and a fax number, one attachment with the URL, which I copied and pasted. So this is how you use that attachment URL. I’m also setting “HoldForPreview” to true on this.

Now, if I wanted to, I could actually turn this into a form and tell it that it should be encoded in JSON, but it’s difficult to do some of these multiple value things, like adding multiple recipients there, so I usually generate the JSON and paste it in by hand.

So at this point, I’ve got my authorization, I’ve got my payload, I’ve got my attachment URL, I’ve got my destination, name and fax number, so I can hit send.

It’s complaining because I didn’t define a content type. In this case, that’s because the first time I did it I uploaded a file which overrides the content type, but this time I do actually need to define it.

I need my actual JSON content type, not javascript. So, that has been uploaded.

Now, once again, I have an empty body in my response, so I want to look at the headers to determine what the result is. In this case, I got my 201 CREATED response telling me it successfully created the object, and I got a location. Now I can turn around and do a “get” to that location to go see the status of that send job. So I’m going to do a “get”, I’m going to add my java ID, 204, and that’s going to give me back a JSON object containing information on that job.

I can see that it is currently processing. If I go over to FaxUtil and go look in my administrator account, there is my fax to test, 1234. This is the one that we just did, it is held for preview because we included that in our send job  creation. When I open this, what you’re going to see is that there is actually two cover sheets on this because that tiff I used was a fax that already had a cover sheet on it, so this is the new one that was just generated.

This is the one that was already there from my sample image, and there is my sample library document, which was the second page of that tiff.

So there we go, we have sent a fax using an attachment through the web API.

*Very good. Now if they wanted to get a list of the faxes that were in that mailbox, how would they do that?*

So the send jobs endpoint here has several parameters it can take. If I just call the send jobs endpoint it’s going to show me all of the send jobs that are in the users that I have access to.

If I want to see the jobs that are just associated with a single user, then I can actually add a parameter to my request up here. I can do this by using the form over here, or I can just put in a “?userid=”. I do need to know what user ID I wanna use. I can add a user ID there. If I shrink this back down you’ll see that it adds “?userid=” and ID number there. Now it will return me all of the send jobs that are in that box.

Send jobs represent a container that can potentially contain multiple faxes. So if I sent a send jobs to three different recipients, RightFax is going to split that into three different documents. So we can also do this same request instead of send jobs, by documents, which is going to let me see all of the documents in that user. Those individual documents also have statuses.

So the send job is a master container that represents potentially multiple faxes and a document is always an individual fax.

*Very good. As of right now, in May 2017, when this is recorded, there is a bug with the advanced rest client for chrome where you must use chrome version 55 or earlier. This should be resolved according to google, but as of right now if you have issues with it, that would be one option to check out.*