Getting started

Step 1

Get your project ID and credentials

This guide will instruct you on how to get started using the Fax API. Before you can start sending and receiving faxes, you need to complete some basic configuration steps.

Let's get started!

Account required!

Using the Fax API requires signing up for a free account on the Sinch Build Dashboard. If you haven't already done so, sign up now!

1. Get your Project ID and credentials

Get your project ID and create your access key: First, you'll need your project ID and to generate access keys. Access keys are used to authenticate calls when using Fax API. You can generate access keys and find your project ID in the Sinch Build Dashboard.

You'll need this info later!

Make sure you have your access key, access key secret, and project ID readily available. This information will be required when making any API calls. The access key and access key secret must be recorded during access key creation.

Important!

The access key will be readily visible. The access key secret, however, will only be visible upon new key creation. Create a new key and then save your key secret in a safe place.

You will need both the access key and the access key secret for most endpoints in the Fax API.

2. Get a number

Get your free Sinch testing number. When you sign up for a Sinch Build Dashboard account, you get a free virtual number for testing. You must activate your test number before you can use it. To activate your number, simply click the link.

To send and receive faxes, you must have a Sinch number assigned to your default Fax service.

To configure it to use with the Fax API, in your dashboard select the number you want and under the Voice Configuration section ensure you have selected Fax.

Note:

While only one number is required, if you will have multiple services, we recommend having a number assigned to each service and set that number as the default number for that service.

3. Send a fax

Now you're ready to start sending faxes with the API.

The payload, along with instructions on how to populate placeholder variables, is below. Alternatively, each tab features a guide that will walk you through setting up a simple application in the identified coding language (make sure you bring all the information you gathered during this process!):

Send a fax using the Sinch CLI

The Sinch CLI is the easiest way to send a fax using the Fax API.

Prerequisites

You'll need Node.js and NPM installed first!

Install the Sinch CLI with the following command:
```
npm install -g @sinch/cli
```
Next, create the authentication config files for the CLI using the following command:
```
sinch auth login
```
You will be prompted to enter your Project ID, Access Key and Access Secret.
Now you're ready to send a fax. Enter the following command:
```
sinch fax send --to <your_fax_number> --file <path/to/file>
```
Change your_fax_number> to the E.164 phone number to which you want to send the fax, and change <path/to/file> to the file you want to send. You should receive a fax to the number you specified.

4. Receive a fax

You can also receive faxes using the Fax API. The easiest way to receive a fax sent to your Sinch number is to set up an email address in the Build Dashboard in the Fax to Email tab of your Fax service. Alternatively, each tab below features a guide that will walk you through setting up a simple server application in the identified coding language (make sure you bring all the information you gathered during this process!):

Handle an incoming fax with Node.js

Before you can get started, you need the following already set up:

NPM and a familiarity with how to install packages.
Node.js and a familiarity with how to create a new app.
A Sinch phone number configured for the Fax API.

To quickly get started setting up a simple client application using the Node.js SDK:

First, we'll open a tunnel which will allow your machine to receive requests from the Sinch servers. We are using ngrok for this. If you don't have ngrok installed already, install it with the following command:
```
npm install ngrok -g
```
Open a terminal or command prompt and enter:
```
ngrok http 3001
```
Copy the HTTPS address that ends with .ngrok.io to save for a future step.
If you haven't already, clone the sinch-sdk-node repository.
Navigate to the examples/getting-started/fax/receive-fax/ folder.
Open a command prompt or terminal and run the following command to install the necessary dependencies:
```
npm install
```

Rename the .env.example file to .env. Uncomment SINCH_FAX_SERVICE_ID and WEBHOOK_URL. Using the access key credentials from your Sinch Build Dashboard, populate the following fields with your values:

Field	Description
SINCH_PROJECT_ID	The unique ID of your Project.
SINCH_KEY_ID	The unique ID of your access key.
SINCH_KEY_SECRET	The secret that goes with your access key. Note: For security reasons, this secret is only visible right after access key creation.
SINCH_FAX_SERVICE_ID	The unique ID for your fax service
WEBHOOK_URL	The ngrok URL you saved from step 3.

Save the file.

Start your server

At this point, you can start your server with the following command:

npm start

server.js

import express from 'express';
import { SinchClient } from '@sinch/sdk-core';
import { faxController } from './fax/controller.js';
import * as dotenv from 'dotenv';
dotenv.config();

const app = express();
const port = process.env.PORT || 3001;

/** @type {import('@sinch/sdk-core').SinchClientParameters} */
const sinchClientParameters = {
  projectId: process.env.SINCH_PROJECT_ID,
  keyId: process.env.SINCH_KEY_ID,
  keySecret: process.env.SINCH_KEY_SECRET,
};

app.use(express.json({ limit: '25mb' }));
app.use(express.urlencoded({ limit: '25mb', extended: true }));

faxController(app);

const updateIncomingWebhookUrl = async () => {
  const serviceId = process.env.SINCH_FAX_SERVICE_ID;
  const webhookUrl = process.env.WEBHOOK_URL;

  if (!serviceId || !webhookUrl) {
    return;
  }

  const sinchClient = new SinchClient(sinchClientParameters);
  const response = await sinchClient.fax.services.update({
    serviceId,
    updateServiceRequestBody: {
      incomingWebhookUrl: webhookUrl,
      webhookContentType: 'application/json',
    },
  });

  console.log(`Incoming webhook URL updated to ${response.incomingWebhookUrl}`);
};

app.listen(port, async () => {
  console.log(`Server is listening on port ${port}`);
  try {
    await updateIncomingWebhookUrl();
  } catch (error) {
    console.error('Failed to update incoming webhook URL:', error);
  }
});

This code starts your webserver and updates your incoming webhook URL. We'll come back to what those things are in a moment.

You should notice a few things.

First, your console should show that the server has started on port 3001 of your localhost.
Additionally, you should see a message in your console that the incoming webhook URL for your fax service was updated automatically. There is code in the sample that makes a request to the Fax API to update the incoming webhook URL.

Tip:

You can also update your incoming webhook URL in the dashboard yourself. Navigate to your fax services on your dashboard. Next to your service click the Edit button. You'll see a field labeled "Incoming webhook URL." Enter your URL into that field and click Save.

Now your server is listening and your incoming webhook URL is configured, so you're almost ready to test everything and send a fax that you can receive. But before we do, let's take a closer look at webhooks. If you already know about webhooks, skip right to sending yourself a fax.

Understanding webhooks

Webhooks (also known as "callbacks" or "notifications") are the method that the Fax API uses to inform you when your Sinch number is sent a fax. Basically, a notification is a request that the Sinch servers send to your server whenever something happens (otherwise known as an "event"), such as when you send or receive a fax. There are two different kinds of events, the Fax Completed and the Incoming Fax event, but the one we're concerned about is the Incoming Fax event.

An Incoming Fax event happens whenever someone sends a fax to one of your Sinch numbers. All of the notification events the Fax API sends expect a 200 OK response in return.

And that's it! Now we can test.

Send your Sinch number a fax

Using the app we created in the previous step, send a fax to your Sinch number. The fax should be picked up by the Sinch servers and a PDF of your fax will be downloaded to your machine. Now you know how to handle an incoming fax.