Getting Started

DOCS is a secure and fully digital document transfer service. The service replaces traditional fax systems without the need for copper lines, fax machines, or unreliable IP telephony and transfer documents encrypted. All data is processed within Sweden, ensuring high security and privacy compliance.

With the Generic DOCS API, you can integrate both digital faxing and Direct File Transfer (DFT) directly into your applications. Upload one or more files, specify the recipient, and the platform will automatically determine whether the delivery should be done with fax or with DFT which require the recipient has DFT enabled. Dialing, retries, transmission, and detailed delivery reporting are all handled by the platform. Every step—from Sent to Delivered or Failed—can be monitored through the API.

To use the DOCS API, you will need an account with Generic and API access enabled for your service. Please contact our support team or your sales representative to obtain your credentials. Once your account is active, you can begin sending documents through our RESTful API.

Base URL: https://api.genericmobile.se/Docs/api/v2

All API endpoints described in this documentation are relative to the base URL above. For example, a POST request to send a message would be made to https://api.genericmobile.se/Docs/api/v2/Send.

Authentication

Authentication with API key

curl -X POST https://api.genericmobile.se/Docs/v2/send \
  -H 'Authorization: Bearer b8b90be1-5e48-4c53-af3d-3293bd4a9229' \
  -H 'Content-Type: multipart/form-data' \
  -F 'senderFaxNumber=+4612345678' \
  -F 'recipientFaxNumber=+46927654321' \
  -F 'allowDirectFileTransfer=false' \
  -F 'deliveryReportUrl=https://example.com/fax/callback' \
  -F 'file=@document.pdf'

  200 OK
  {
      "recipientFaxNumber": "+46927654321",
      "faxId": "a3d92fa1-9a33-4033-a4b0-4a20bd448c78"
  }

All requests to the DOCS API require authentication via an API key. This ensures that only authorized users can send docs or access information.

Bearer API Key

Authenticate your requests by including an Authorization header with the value Bearer b8b90be1-5e48-4c53-af3d-3293bd4a9229, replacing b8b90be1-5e48-4c53-af3d-3293bd4a9229 with your actual key. API keys are generated and managed through our customer platform.

401 Unauthorized

If your request lacks a valid API key or proper permissions, you'll receive a 401 Unauthorized response. Verify that your authentication details are correct and have appropriate permissions.

Send a document

Example 1: Send a document

curl -X POST https://api.genericmobile.se/Docs/v2/send \
  -H 'Authorization: Bearer b8b90be1-5e48-4c53-af3d-3293bd4a9229' \
  -H 'Content-Type: multipart/form-data' \
  -F "senderFaxNumber=+4612345678" \
  -F "recipientFaxNumber=+46927654321" \
  -F "file=@document.pdf"

200 OK
{
  "recipientFaxNumber": "+46927654321",
  "faxId": "a3d92fa1-9a33-4033-a4b0-4a20bd448c78",
  "directFileTransfer": false
}

Example 2: Send a document with Direct File Transfer (DFT)

curl -X POST https://api.genericmobile.se/Docs/v2/send \
  -H 'Authorization: Bearer b8b90be1-5e48-4c53-af3d-3293bd4a9229' \
  -H 'Content-Type: multipart/form-data' \
  -F "senderFaxNumber=+4612345678" \
  -F "recipientFaxNumber=+46927654321" \
  -F "allowDirectFileTransfer=true" \
  -F "file=@document.docx"

200 OK
{
  "recipientFaxNumber": "+46927654321",
  "faxId": "b7f5d3e9-1a2c-4d8b-9a0e-7f5c2a1e4f88",
  "directFileTransfer": true
}

Example 3: Send multiple documents with a Direct File Transfer (DFT)

curl -X POST https://api.genericmobile.se/Docs/v2/send \
  -H 'Authorization: Bearer b8b90be1-5e48-4c53-af3d-3293bd4a9229' \
  -H 'Content-Type: multipart/form-data' \
  -F "senderFaxNumber=+4612345678" \
  -F "recipientFaxNumber=+46927654321" \
  -F "allowDirectFileTransfer=true" \
  -F "file=@document.xlsx" \
  -F "file=@image2.png" \
  -F "file=@report3.pdf"

200 OK
{
  "recipientFaxNumber": "+46927654321",
  "faxId": "b7f5d3e9-1a2c-4d8b-9a0e-7f5c2a1e4f88",
  "directFileTransfer": true
}

The DOCS API allows you to send documents by uploading one or more files along with the sender and recipient telephone numbers. You can send up to 5 files in a single request, and the documents can be delivered to one or multiple recipients.

If the recipient supports DFT and the allowDirectFileTransfer parameter is set to true, documents will be delivered in their original format. With the allowDirectFileTransfer set to false or when the recipient doesn't support DFT, the content will be sent with fax.

POST /Send

In its simplest form, sending a document requires only the essential fields: senderFaxNumber, recipientFaxNumber, and at least one file in the multipart form-data request.

Below is a summary of the key parameters used when sending a simple document: senderFaxNumber, recipientFaxNumber, file Example: Send a document.

If you want the document to be delivered using Direct File Transfer (DFT), you must set: allowDirectFileTransfer to true

When enabled, the API attempts DFT delivery first. If the recipient does not support DFT, the request will fall back to fax.

HTTP Response

200 OK

A successful request contains a send response object.

Send response object

Response object example

200 OK
{
  "recipientFaxNumber": "+46927654321",
  "faxId": "b7f5d3e9-1a2c-4d8b-9a0e-7f5c2a1e4f88",
  "directFileTransfer": true
}

Retrieve documents

Example 2: Retrieve documents

curl -X POST "https://api.genericmobile.se/Docs/v2/retrieve" \
  -H "Content-Type: application/json" \
  -d '{
        "dateFrom": "2023-05-01T12:00:00",
        "dateTo":   "2023-05-02T12:00:00"
      }'

200 OK
[
  {
    "faxId": "553595dd-2df7-40c4-b081-c22a5efcd1d2",
    "faxTime": "2023-05-01T14:47:33",
    "senderFaxNumber": "+46927654321",
    "recipientFaxNumber": "+4612345678",
    "status": "Received",
    "statusTime": "2023-05-01T14:47:33",
    "files": [
      {
        "fileId": "207af385-93b9-4206-86f8-a225a8992fe2",
        "fileName": "20250411_0916344612345678.pdf"
      }
    ],
    "type": "DirectFileTransfer"
  }
]

POST /Retrieve

To retrieve multiple documents, supply dateFrom and dateTo values in the request body. The API returns up to the first 100 document objects within the specified time span.

Note: Only metadata is returned in this call, including file names and fileId's. To get the actual file content, use the retrieve file endpoint.

If the recipient has Direct File Transfer (DFT) enabled, the file is stored in its original uploaded format. If DFT is not enabled, the document will be returned as a PDF when retrieved.

HTTP Response

200 OK

A successful request contains a retrieve documents response object.

Retrieve documents response object

Response object example

200 OK
[
  {
    "faxId": "553595dd-2df7-40c4-b081-c22a5efcd1d2",
    "faxTime": "2023-05-01T14:47:33",
    "senderFaxNumber": "+46927654321",
    "recipientFaxNumber": "+4612345678",
    "status": "Received",
    "statusTime": "2023-05-01T14:47:33",
    "files": [
      {
        "fileId": "207af385-93b9-4206-86f8-a225a8992fe2",
        "fileName": "20250411_0916344612345678.pdf"
      }
    ],
    "type": "DirectFileTransfer"
  }
]

Retrieve file

GET /File

Example: Retrieve file

curl -X GET "https://api.genericmobile.se/Docs/v2/File/207af385-93b9-4206-86f8-a225a8992fe2" \
  -H "Authorization: Bearer b8b90be1-5e48-4c53-af3d-3293bd4a9229" \

200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="20250411_09163446927654321.pdf"
Content-Length: 482193

Use this endpoint to download the actual file (PDF, TIFF, DOCX, or any other supported format) associated with a document. You obtain the fileId from the document metadata returned by the Retrieve documents endpoint or Retrieve status enpoint.

If the document was sent using DFT, the downloaded file will be the original unmodified file. If DFT was not used, the file returned will be the processed fax-rendered version (e.g., PDF/TIFF).

The response is the raw binary file, returned with the correct Content-Type and original file name.

Path Parameter

Delete docs

DELETE /Delete

Example: Delete document

curl -X DELETE "https://api.genericmobile.se/Docs/v2/Delete" \
  -H "Content-Type: application/json" \
  -d '{
        "faxId": "553595dd-2df7-40c4-b081-c22a5efcd1d2"
      }'

204 No content

Deletes a document transmission and its associated files based on the provided faxId. This operation removes only the file content (such as rendered document files or original DFT files) but does not delete the document metadata record itself.

Metadata such as timestamps, recipient number, delivery status, and document transmission type remains available for auditing and history purposes.

Retrieve status

POST /Retrieve

Example 1: Retrieve document

curl -X POST "https://api.genericmobile.se/Docs/v2/retrieve" \
  -H "Content-Type: application/json" \
  -d '{
        "faxId": "553595dd-2df7-40c4-b081-c22a5efcd1d2"
      }'

200 OK
{
  "faxId": "553595dd-2df7-40c4-b081-c22a5efcd1d2",
  "faxTime": "2023-05-01T14:47:33",
  "senderFaxNumber": "+46927654321",
  "recipientFaxNumber": "+4612345678",
  "status": "Received",
  "statusTime": "2023-05-01T14:47:33",
  "files": [
    {
      "fileId": "207af385-93b9-4206-86f8-a225a8992fe2",
      "fileName": "20250411_0916344612345678.pdf"
    }
  ],
  "type": "Fax"
}

This endpoint is primarily used to retrieve the current delivery status of a specific document. In addition to status information, it returns the document metadata, including sender and recipient details, timestamps, and references to attached files (fileName and fileId).

The actual file content is not included in this response and must be retrieved separately using the Retrieve file endpoint.

Possible status values include:

Sending – The document is currently being processed or transmitted

Sent – Successfully sent

Failed – Delivery failed

Received – Successfully received by the destination

Opened – The recipient has opened the document (DFT only, if supported)

Read – The document has been read, downloaded, or printed by the recipient (DFT only, if supported)

HTTP Response

200 OK

A successful request contains a status response object.

Status response object

Response object example

200 OK
{
  "faxId": "553595dd-2df7-40c4-b081-c22a5efcd1d2",
  "faxTime": "2023-05-01T14:47:33",
  "senderFaxNumber": "+46927654321",
  "recipientFaxNumber": "+4612345678",
  "status": "Received",
  "statusTime": "2023-05-01T14:47:33",
  "files": [
    {
      "fileId": "207af385-93b9-4206-86f8-a225a8992fe2",
      "fileName": "20250411_0916344612345678.pdf"
    }
  ],
  "type": "Fax"
}

Capability Check DFT

POST /CheckDirectFileTransfer

Example: Check if recipient supports (DFT)

curl -X POST "https://api.genericmobile.se/Docs/v2/CheckDirectFileTransfer" \
  -H "Content-Type: application/json" \
  -d '{
        "recipientFaxNumber": "+46927654321"
      }'

200 OK
{
  "recipientFaxNumber": "+46927654321",
  "directFileTransferSupported": true
}

This endpoint is typically used to verify whether the recipient number supports Direct File Transfer (DFT). Based on the result, you can decide whether to set allowDirectFileTransfer to true when sending a document.

Error Handling and Response Codes

The Docs API uses standard HTTP status codes to indicate whether a request succeeded or failed. Depending on the endpoint, responses may return JSON metadata (for document queries) or binary data (for file downloads). Your integration should check both the status code and the response body when applicable. Below is a summary of the expected response codes for the Docs API.

Success Responses

Client Error Responses

Server Error Responses

Supported File Types and Extensions

The DOCS API accepts a wide range of document and image formats. Files must match one of the supported MIME types and extensions listed below; otherwise, the API will return 400 Bad Request.

Both the MIME type (sent from the client) and the file extension are validated during upload.

Supported MIME Types

Supported File Extensions

Notes

Up to 5 files can be uploaded in a single request.
Each file may have a maximum size of 16 MB.

All files must be properly encoded multipart/form-data when calling /Send.

For Direct File Transfer (DFT), source files are delivered in their original format to recipients who have DFT enabled.

For fax, files may be converted to TIFF or PDF internally depending on processing requirements.