NUACOM API

Messaging

Fax

Fax is the account's fax-to-email service. A number NUACOM has set up for fax receives faxes and delivers each one by email, as a PDF, to the addresses you list for that number; the addresses you list as its senders may fax out through it, from the portal or from your own code. This group holds the account's numbers with their two email lists, the sending endpoint, the history of received and sent faxes, the processing queue, the file download and the history delete. Getting and assigning numbers is covered in Numbers; how long fax history and files are kept is the account's fax data retention setting, see Data Retention.

Workflow (what the portal does)

  1. Numbers and their email lists (the portal's Fax to Email settings page): GET /v2/fax answers a plain array with one object per number assigned to the account: id (the number id every endpoint below takes), number (international digits without +, 35312345678), localized_number (the same number in the account country's national format, 01 234 5678, or in E.164 with + when it does not belong to that country), name (the line's label when the number is set to use it, otherwise null), inbound_emails and outbound_emails (arrays of addresses, empty when none are set). There is no paging, search or sort; the portal filters the array itself. Every active number of the account is listed, fax-capable or not.
  2. Set the lists: PUT /v2/fax/{numberId}/inbound_emails with {"emails": ["fax@example.com"]} sets who receives the faxes arriving on the number; PUT /v2/fax/{numberId}/outbound_emails sets who may send through it. Each PUT replaces the whole list and answers 204. emails must be present ([] clears the list), every entry must be a valid address, and an address may not appear twice whatever its case (422); addresses are stored in lower case. An outbound address identifies the number it sends from, so it can be registered on one number only: when any address in the list is already on another number, the request answers 400 with error_code FAX-ROUTING-EMAIL-ALREADY-REGISTERED and a message naming the addresses, and the list is left as it was. Inbound addresses may repeat across numbers. GET /v2/fax/{numberId}/inbound_emails and GET /v2/fax/{numberId}/outbound_emails answer one list as a plain array of strings; DELETE /v2/fax/{numberId}/inbound_emails and DELETE /v2/fax/{numberId}/outbound_emails clear it (204). An id that is not a number of the account answers 404.
  3. Inbox and Outbox: GET /v2/fax/history is the fax list, paginated as {"data": [rows], "links": {…}, "meta": {"current_page", "last_page", "per_page", "total", …}}. Parameters, all optional: direction (1 for received faxes, the Inbox; 0 for sent ones, the Outbox; omit for both), search (a substring of email, sender or destination; for a number send digits only, 353861234567), page, perPage (default 15, no maximum), sortBy (direction, email, sender, destination, send_timestamp, status or status_timestamp) and sortDir (asc or desc, default desc). Without sortBy the rows come newest first, by id; with it, ties are broken by id in the same direction. Rows deleted in step 7 are left out. The portal asks for direction per tab with perPage=15, sortBy=send_timestamp and sortDir=desc.
  4. Processing: GET /v2/fax/queue lists the faxes accepted but not yet processed, with the same parameters except that sortBy is one of direction, email, sender, destination or timestamp. Rows are {"id", "direction", "email", "sender", "destination", "timestamp"}; a fax leaves the queue when it gets its history row. The portal shows the sent ones (direction=0, perPage=100, newest first) on top of the first Outbox page as Processing. A queued fax has no file to download and cannot be deleted or cancelled.
  5. Send a fax: pick the sender from GET /v2/fax/can_send_fax, the active numbers that have at least one outbound address, answered as the rows of step 1 without the two email lists. Then POST /v2/fax/{numberId}/send_fax as multipart/form-data with recipientNumber (a + followed by 9 to 15 digits and nothing else, +353861234567) and files[], one or more JPEG or PDF files (checked by content, not by name) of at most 5 MB together (5,242,880 bytes). The fax is submitted on behalf of the first address in the number's outbound_emails: a number without one answers 400 with error_code FAX-SEND-NO-EMAILS, an id that is not an active number of the account 404, and a hand-over NUACOM's fax service refuses 400 with FAX-SEND-ERROR. Success is 204 with no body and no id: the request only confirms that the fax was accepted. It appears in the queue, then in the Outbox with status 1 (pending) until the transmission ends, when status and status_timestamp are updated.
  6. Download: GET /v2/fax/{faxRecord}/file with a history row's id answers the stored document itself: the body is the file, Content-Type is its detected type and Content-Disposition: attachment; filename="…" carries the file name (the header is exposed to browsers through Access-Control-Expose-Headers). An unknown id answers 404, a row of another account 403. The portal downloads a selection one file at a time; there is no bulk download.
  7. Delete from history: DELETE /v2/fax/history with ids, an array of history row ids (the portal sends a JSON body, {"ids": [12, 15]}; ids[]=12&ids[]=15 in the query string works too), hides the rows from the history and answers 204. It is all or nothing: when any id is not a visible history row of the account, the request answers 400 with message Records with the following IDs were not found: 15 and nothing is hidden. The ids must be distinct integers (422). There is no undo, the file stays downloadable by id, and a fax that is still being sent is not stopped.
curl -X POST https://api.api-nuacom.com/v2/fax/1234/send_fax \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'recipientNumber=+353861234567' \
  -F 'files[]=@invoice.pdf' \
  -F 'files[]=@signature.jpg'
# → 204 No Content; the fax shows in GET /v2/fax/queue, then in GET /v2/fax/history?direction=0

Reading a row

  • direction is 1 for a received fax and 0 for a sent one.
  • sender and destination are JSON integers, the two numbers as international digits without + (353861234567). On a received fax destination is your number; on a sent fax sender is.
  • email is the address on the fax: the inbound address a received fax was delivered to, or the outbound address a sent fax was submitted from.
  • status (history only) is the outcome, simplified from the transmission result:
status Meaning
1 Pending: queued or being transmitted
2 Done: a sent fax was delivered, a received fax was emailed
3 Failed: the line was busy or not answered, the call ended with no result, the number had no inbound address to deliver to, or the email could not be sent
4 Undefined: a result NUACOM does not recognise
5 Unreachable: the destination is out of order or does not support fax
  • send_timestamp is when the fax was received or submitted and status_timestamp when status last changed; the queue's timestamp is when the fax entered the queue. On the legacy date contract all three are UTC with microseconds (2026-05-01T13:30:00.000000Z); with the ISO dates option they follow X-Timezone (2026-05-01T14:30:00+01:00), see Dates and timezones.
{
  "id": 5821,
  "direction": 0,
  "email": "office@example.com",
  "sender": 35312345678,
  "destination": 353861234567,
  "send_timestamp": "2026-05-01T13:30:00.000000Z",
  "status": 2,
  "status_timestamp": "2026-05-01T13:31:12.000000Z"
}

Roles and access

  • Every endpoint of the group is open to any authenticated user of the account; none needs an account admin.
  • Everything is scoped to the token's account: a number of another account answers 404, a file of another account 403.
  • Whether a number can actually receive faxes depends on how NUACOM provisioned it; the API does not check this, which is why GET /v2/fax lists every number of the account.
  • The ISO dates option (per account) changes the timestamp format, see Dates and timezones.

Pitfalls

  • direction is 1 for received and 0 for sent, the reverse of what you might expect.
  • Sending is asynchronous. 204 means accepted, not delivered, and nothing in the response identifies the fax. Poll the Outbox: the newest row with your destination moves from status 1 to 2, 3 or 5. A fax cannot be cancelled once accepted.
  • GET /v2/fax lists every active number of the account, with or without email lists; only GET /v2/fax/can_send_fax lists the ones that can send, and its rows carry no inbound_emails or outbound_emails keys.
  • The two PUT endpoints replace the whole list: send the complete list, not just the new address. Outbound addresses are unique across every NUACOM number, not only the account's, so a 400 FAX-ROUTING-EMAIL-ALREADY-REGISTERED can name an address the account has never used.
  • search matches numbers as stored, digits only: +353861234567 never matches, 353861234567 does.
  • sender and destination are integers in JSON, not strings.
  • sortBy=status sorts by the underlying transmission code, so the order does not follow the status values you receive.
  • perPage has no upper bound.
  • Deleting hides rows and is all or nothing; an id already deleted counts as not found (400). The file is kept and GET /v2/fax/{faxRecord}/file still serves it.
  • Queue ids and history ids are different sequences: never pass a queue id to the file or delete endpoints.
  • recipientNumber must be exactly + and 9 to 15 digits: +353 86 123 4567, 00353861234567 and 0861234567 answer 422. Per-file validation errors are keyed files.0, files.1, …, and the size error reads The combined size of all files has exceeded 5120 kilobytes.
  • The email-list GET and PUT answer 404 for a number that is no longer active on the account, while DELETE still clears its lists.