Here is a tutorial on how to send a fax using the RightFax 10.6 Web Services API.
Sending Fax and Attachments with Web Services API
Alright, so were going to walk through sending a fax through the RightFax web API with an attachment today.
So were on a server named HQRF, so youre 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 Ive got some pre-filled URLs in here. So Im 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, its going to ask me for authentication. Im 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 its going to return the basic information about the API. Its going to tell you your version number, your build number, who youre logged in as, and whether its a RightFax or a Windows account.
Again, Windows-linked accounts are a little more problematic, theres a lot more configuration to make those work.
Its also going to give you some links to your account and your user. Its 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 youre logged in as.
We use this primarily just to make sure that were authenticated correctly, and that we can see what our username is.
So at this point, were authenticated. This is also generated (my authorization header). In the advanced rest client, once youve generated this once, its going to stay in there as you modify your request, so that you dont 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 Im using, I need to upload that.
So Im going to change this to be a post request. Im going to upload this to our attachments endpoint, which you can see I also have in there.
For the body of my request Im going to go over to files. Tell it to add a file, choose that file, and grab a file from there.
You can see its automatically going to add a content type header, so I dont need to worry about changing my headers here. So Im 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 youre 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 Im actually going to take that URL, and Im going to use it in my next request.
Then the final request that Im going to make here to actually send this is Im going to go over to our send jobs endpoint. Im going to do a post. Im going to remove that file and do a raw payload, and Im 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. Im 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 its 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, Ive got my authorization, Ive got my payload, Ive got my attachment URL, Ive got my destination, name and fax number, so I can hit send.
Its complaining because I didnt define a content type. In this case, thats 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 Im going to do a get, Im going to add my java ID, 204, and thats 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 youre 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 its 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 youll 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.*