FaxApi Logo
API docs by Redocly

Faxsuite RESTful API (4.0.0)

Download OpenAPI specification:Download

API Support: support@fax-api.de URL: https://www.fax-api.de/support/ Terms of Service

Einleitung

API Definition

Die RESTful API basiert auf den OpenAPI v3.0.3 Spezifikationen. OpenAPI Spezifikationen (OAS) definieren eine standardisierte und programmiersprachenunabhängige Schnittstellenbeschreibung für RESTful APIs. Diese Schnittstelle ist nutzbar ohne dass der Zugang zum Quellcode, zusätzliche Dokumentation oder die Untersuchung des Netzwerk-Traffics erforderlich sind. Somit kann ein Nutzer den Dienst mit einem Minimum an Implementierungslogik verstehen, mit ihm interagieren und einfach und schnell als API-Schnittstelle in seine eigene Softwareanwendung integrieren.

Weitere Informationen zu OpenAPI finden sie hier: https://www.openapis.org/

Fax-API

Mit unserer Faxsuite können Sie überall und zu jederzeit Faxe senden und empfangen. Neben vielen anderen Funktionalitäten bietet Ihnen unsere Faxsuite auch eine RESTful API-Schnittstelle. Damit können Sie z. B. aus Ihrer eigenen Softwareanwendung Faxe automatisiert versenden. Zeitintensive und teure Investionen in Hardware und Software gehören der Vergangenheit an und sind nicht mehr notwendig.

Um den API-Service nutzen zu können, müssen Sie sich für die Faxsuite anmelden. Ein kostenloser Testzugang kann hier beantragt werden. (To use the API service you need to sign up for the Faxsuite. A free trial access can be requested here)

Mit der Faxsuite haben Sie die Kontrolle über Ihre Fax-Kampagnen. Mit dem kostenlosen Testzugang können Sie alle Faxsuite-Module (Faxmailing, Mail2Fax, Fax-API, Faxdrucker und Faxempfang) unverbindlich ausprobieren. Sie bekommen 10 kostenlose Faxseiten, die Sie zum aktiven Kennenlernen unserer Faxsuite nutzen können. (You can test the Faxsuite modules for four weeks without obligation. You will receive 10 free fax pages with the free trial access)

Nachdem Sie den Zugang beantragt haben, können Sie sich hier in die Faxsuite einloggen. Unter dem Menüpunkt 'Fax-API | Konto verwalten' können Sie ein neues Fax-API Konto erstellen. Bei der Erstellung des Fax-API Kontos wird automatisch ein Autorisierungs-Schlüssel generiert, welchen Sie für den Zugang zur API-Schnittstelle benötigen. (After creating a login you can access the Faxsuite here. In the menu 'FAX-API | Konto verwalten' you can create a new API-Account and receive the related token/key you need to gain access to our API service)

Open API Dokumentation

Die standardisierte API Dokumentation wird Ihnen in zwei unterschiedlichen, als nicht interaktive und interaktive Varianten angeboten:

Name Type Link
Redoc non interactive click here for redoc
Swagger UI interactive (self hosted) click here for swagger

Anleitung

Folgend werden grundlegende Informationen bezüglich der hier vorgestellten API bereitgestellt. Wie z.B. die verfügbaren Ressourcen, potentielle Fehlercodes oder eine kurze Anleitung für die Filterung.

HTTP Methods

Folgende Verben/Methoden werden von der RESTful API verwendet:

Verb Beschreibung
get Liefert einen oder mehrere Einträge zu einer bestimmten Ressource
post Erstellt einen neuen Eintrag zu einer bestimmten Ressource
put Aktualisiert einen Eintrag einer bestimmten Ressource

Status Codes

Die API wird mit einem der folgenden Status Codes antworten:

Code Status Beschreibung
200 SUCCESS Die Anfrage wurde erfolgreich bearbeitet und das Ergebnis der Anfrage wird in der Antwort übertragen.
201 CREATED Die Anfrage wurde erfolgreich bearbeitet. Die angeforderte Ressource wurde vor dem Senden der Antwort erstellt.
400 BAD REQUEST Die Anfrage-Nachricht war fehlerhaft aufgebaut. Der Error Response beschreibt das Problem detailiert.
404 NOT FOUND Die angeforderte Ressource wurde nicht gefunden.
429 TOO MANY REQUESTS Der Client hat zu viele Anfragen in einem bestimmten Zeitraum gesendet.
500 INTERNAL SERVER ERROR Dies ist ein „Sammel-Statuscode“ für unerwartete Serverfehler. Bitte kontakieren Sie den Support.
503 SERVICE UNAVAILABLE Der Server steht temporär nicht zur Verfügung, zum Beispiel wegen Überlastung oder Wartungsarbeiten.

Error Codes

Die Fax-API unterstützt detailierte Fehlerbeschreibungen mit eindeutigen Codes:

Code Type DE EN
800 Service Exception Unbekannter Fehler Unknown error
801 Service Exception Datenbankfehler Database exception
802 Service Exception Zu viele Anfragen Too many requests
803 Service Exception Service ist aktuell nicht verfügbar Service is currently not available
804 Service Exception Ressource nicht gefunden Resource not found
810 Authentification Exception Unbekannter Authentifizierungsfehler Unknown authentication error
811 Authentification Exception API Konto nicht gefunden API Account not found
812 Authentification Exception API Konto nicht aktiv API Account is not active
813 Authentification Exception Benutzerkonto nicht aktiv User Account is not active
820 Parameter Exception Fehlender/ungültiger Autorisierungsschlüssel Missing/invalid authorization key
821 Parameter Exception Fehlender/ungültiger Function Parameter Missing/invalid function parameter
822 Parameter Exception Fehlender/ungültiger Path Parameter Missing/invalid path parameter
823 Parameter Exception Fehlender/ungültiger Query Parameter Missing/invalid query parameter
824 Parameter Exception Fehlender/ungültiger Header Parameter Missing/invalid header parameter
825 Parameter Exception Fehlender/ungültiger Request Parameter Missing/invalid request parameter
830 Resource Exception Element nicht gefunden Element not found
831 Resource Exception Unbekannter Element Fehler Unknown element issue
832 Resource Exception Änderung des Elements nicht möglich Change of element not possible
840 Job Exception Job nicht gefunden Job not found
841 Job Exception Unbekannter Job Fehler Unknown Job issue
842 Job Exception Statusänderung im Job nicht möglich Status change not possible
843 Job Exception Preview im Job nicht verfügbar Preview not available

Ressourcen und Funktionalitäten

Folgende Ressourcen stehen zur Verfügung:

Ressource Verben Endpoint Beschreibung
Jobs get /jobs Abfragen von Jobs (Faxaufträgen). Filterung und Sortierung wird unterstützt
Jobs post /jobs Anlegen von Jobs (Faxauftrag)
JobDetails get /jobs/{id} Abfragen eines Jobs (Faxauftrags)
JobDetails put /jobs/{id} Statusänderung eines Jobs (Faxauftrags)
JobRecipients get /jobs/{id}/recipients Abfragen von Empfängern eines Jobs (Faxauftrag), Filterung und Sortierung wird unterstützt
JobPreview get /jobs/{id}/preview Abfragen des Previews (Ausgangsdokument) eines Jobs (Faxauftrag)
JobTemplates get /jobs/{id}/templates Abfragen der Templates (Eingangsdokumente) eines Jobs (Faxauftrag)
JobsNotifications get /jobs/{id}/notifications Abfragen der eingestellen Benachrichtigungen eines Jobs (Faxauftrag)
Recipients get /recipients Abfragen von Empfängern aller Jobs (Faxaufträgen), Filterung und Sortierung wird unterstützt
System get /health Abfragen des aktuellen API-Zustands

Pagination

Einige Responses werden in Seiten zusammengefasst geliefert. In Default werden 100 Elemente geliefert beginnend mit dem ersten Element 0. Dies kann mit dem Pagination Parameter in der URL angepasst werden ?objectLimit={limit}&objectOffset={page}

Query Parameter

Parameter Type Default Beschreibung
objectLimit integer 100 Beschreibt die Anzahl der Elemente im Response
objectOffset integer 0 Beschreibt den zu verwendenden Offset im Response

Response

Attribute Type Beschreibung
total integer Beschreibt die Anzahl aller vorhandenen Elemente
offset integer Beschreibt den aktuell verwendeten offset
count integer Beschreibt die Anzahl der Elemente im Feld 'data'
data array Liste der angeforderten Ressource

Filtern und Sortieren

Get Anfragen mit Pagination ermöglichen in der Regel zusätzliches Filtern und Sortieren der zurückgelieferten Liste.

Filtern

Um eine Filterung zu nutzen, können Query Parameter verwendet werden. Siehe in der jeweiligen Ressource, welche unterstützt werden.
?{filterA}={valueA}&{filterB}={valueB}

In der Ressource Jobs könnte diese zum Beispiel wie folgt aussehen:
?filterTitle=Kunde&filterStatus=scheduled

Sortieren

Für das Sortieren sind zwei Query Parameter vorgesehen:

Parameter Type Default Beschreibung
sortField enum (abhänig der Ressource) null Beschreibt das zu sortierende Attribut
sortOrder enum (asc, desc) asc Beschreibt die Sortierung des Attributs (aufsteigend oder absteigend)

Beispiel für die Ressource Jobs:
?sortField=Status&sortOrder=desc

Zeitwerte

Einige Responses liefern in ihren Datenfeldern einen Zeitstempel zurück oder können als Filter in Suchanfragen verwendet werden. Das Format muss dabei dem ISO 8601 entsprechen und Datum sowie Zeitangaben beinhalten wie z.B. '2023-01-01T10:00:00+02:00'. Bitte beachten Sie bei Verwendung eines Zeitstempels als query parameter in der URL ein urlencoding zu verwenden 2023-01-01T10%3A00%3A00%2B01%3A00.

Job Status

Folgende Zustände kann ein Faxauftrag (Job) haben:

Status Beschreibung
scheduling Der Faxauftrag wird für den Versand vorbereitet
scheduled Der Faxauftrag wird für den Versand bereit. Es wurden noch kein Einzelversand durchgeführt
processing Der Faxauftrag befindet sich im Versand. Es wurden mindestens ein Einzelversand durchgeführt
halted Der Faxauftrag wurde angehalten und kann fortgesetzt werden
locked Der Faxauftrag wurde vom Support angehalten und kann nur vom Support wieder fortgesetzt werden
canceled Der Faxauftrag wurde abgebrochen und kann nicht mehr fortgesetzt werden
finished Der Faxauftrag wurde erfolgreich beendet. Beachte ein erfolgreicher Faxauftrag ist nicht gleichzusetzen mit einem erfolgreichen Einzelversand
error Der Faxauftrag wurde nicht erfolgreich beendet. Beachte den Fehlercode, diese beinhaltet eine detaillierte Beschreibung des Problems

Zur detaillierteren Prüfung eines erfolgreichen Faxversands empfehlen wir den Recipient Status zu verwenden.

Testing

Nachfolgend werden einige Informationen bereitgestellt, die beim Testen der API-Schnittstelle verwendet werden können.

Endpoints

Es stehen zwei Endpoints zur Verfügung:

| Live | https://service.fax-api.de/4.0/rest |
| Sandbox | https://sandbox.fax-api.de/4.0/rest |

Sandbox

Die Sandbox unterstützt Entwickler bei der Integration von Funktionen der Fax-API in betriebliche Anwendungen. Die Anbindung der Fax-API erfolgt in einer gekapselten Entwicklungsumgebung: der Sandbox, bevor im Zuge der Inbetriebnahme reale Faxaufträge über das Produktivsystem generiert werden.

Die Sandbox stellt einen reduzierten Funktionsumfang zur Verfügung. Dieser verfügt über Entwicklungshilfen wie Fehlersimulatoren.

Testfax

Type Link
PDF Download
HTML Download
TIFF Download

API-Accounts

Key Note
0d269c650e23d76747f8ec8ce87ce8d1 Aktiver Nutzer, inaktiver API Account
f60778208b2ec3aff46bd3586481c934 Inaktiver Nutzer, aktiver API Account

Jobs

Contains resources to obtaining jobs information or creating new jobs

/jobs

Description: Resource to obtain a list of fax jobs

Authorizations:
ApiAuthKey
query Parameters
objectLimit
integer [ 1 .. 100 ]
Default: 100

Query parameter to change de default limitation of objects in the result data array

objectOffset
integer >= 0
Default: 0

Query parameter to change de default offset of objects in the result data array

filterSameAccount
boolean
Default: false

Query parameter to fetch jobs after the api account linked to the used token/key for authorization

filterTitle
string

Query parameter to fetch jobs after his title

filterStatus
string
Enum: "scheduling" "scheduled" "processing" "halted" "locked" "canceled" "finished" "error"

Query parameter to fetch jobs after his status

filterDateFrom
string <date-time>

Query parameter to fetch jobs with a later date in TimeToSend. Can be combined with filterDateTo to define a period of interest. The format must comply with ISO 8601 and must contain date and time, like '2022-01-01T10:00:00+01:00'. Please also consider urlencoding (2022-01-01T10%3A00%3A00%2B01%3A00)

filterDateTo
string <date-time>

Query parameter to fetch jobs with a previous date in TimeToSend. Can be combined with filterDateFrom to define a period of interest. The format must comply with ISO 8601 and must contain date and time, like '2022-01-01T10:00:00+02:00'. Please also consider urlencoding (2022-01-01T10%3A00%3A00%2B01%3A00

filterDateUntilFrom
string <date-time>

Query parameter to fetch jobs with a later date in TimeToSendUntil. Can be combined with filterDateUntilTo to define a period of interest. The format must comply with ISO 8601 and must contain date and time, like '2022-01-01T10:00:00+01:00'. Please also consider urlencoding (2022-01-01T10%3A00%3A00%2B01%3A00)

filterDateUntilTo
string <date-time>

Query parameter to fetch jobs with a previous date in TimeToSendUntil. Can be combined with filterDateUIntilFrom to define a period of interest. The format must comply with ISO 8601 and must contain date and time, like '2022-01-01T10:00:00+02:00'. Please also consider urlencoding (2022-01-01T10%3A00%3A00%2B01%3A00

filterCostCenter
string

Query parameter to fetch jobs after his cost center

sortField
string
Enum: "jobId" "title" "createTime" "timeToSend" "timeToSendUntil"

Available sort options for the result data array.

sortOrder
string
Default: "asc"
Enum: "asc" "desc"

Describes the order for used sort fields

Responses

Request samples 

curl --output './getJobsResponse.json' \
     --header 'X-Auth-Token: xxxx' \
     --header 'Content-Type: application/json' \
     --get \
     --data-urlencode 'filterTitle=xxxx' \
     --data-urlencode 'filterStatus=canceled' \
'https://service.fax-api.de/4.0/rest/jobs'

#use jq for pretty json output 
jq . getJobsResponse.json

Response samples

Content type
application/json
{
  • "total": 100,
  • "offset": 0,
  • "count": 50,
  • "data": [
    ]
}

/jobs

Description: Resource to create a new fax job

Authorizations:
ApiAuthKey
Request Body schema: application/json

Describes the required request body to create a new fax job

object

Describes the request body for the fax job

required
Array of objects (Template) [ 1 .. 5 ]

Describes an array of template documents. One is required. 5 templates are max

Array of objects (JobPostRecipient) [ 0 .. 9999 ]

Describes an array of recipients. One is required if distribution list is not used. 9999 recipient are max

distributionLists
Array of strings >= 0

Describes an array of distribution lists identification numbers. One is required if recipients lists is not used

Responses

Request samples

Content type
application/json
{
  • "options": {
    },
  • "templates": [
    ],
  • "recipients": [
    ],
  • "distributionLists": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "target": ".../jobs/{id}"
}

Job Details

Contains resources about detailed information of a specific job

/jobs/{id}

Description: Obtain information of a specific job

Authorizations:
ApiAuthKey
path Parameters
id
required
string
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Identification number (UUID) of the job

Responses

Request samples 

curl --output './getJobResponse.json' \
     --header 'X-Auth-Token: xxxx' \
     --header 'Content-Type: application/json' \
'https://service.fax-api.de/4.0/rest/jobs/{job-ID}'

#use jq for pretty json output 
jq . getJobResponse.json

Response samples

Content type
application/json
{
  • "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "account": "ApiAccount123",
  • "status": "scheduling",
  • "errorCode": 503,
  • "options": {
    },
  • "info": {
    },
  • "statistics": {
    }
}

/jobs/{id}

Description: Control the transmission of the specific job

Authorizations:
ApiAuthKey
path Parameters
id
required
string
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Identification number (UUID) of the job

Request Body schema: application/json

Describes the required request body to perform an action on the fax job

action
required
string
Enum: "hold" "cancel" "resume"

Describes the action should be performed on the fax job

Responses

Request samples

Content type
application/json
{
  • "action": "hold"
}

Response samples

Content type
application/json
{
  • "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  • "account": "ApiAccount123",
  • "status": "scheduling",
  • "errorCode": 503,
  • "options": {
    },
  • "info": {
    },
  • "statistics": {
    }
}

/jobs/{id}/recipients

Description: Resource to obtain a list of recipients to a specific job

Authorizations:
ApiAuthKey
path Parameters
id
required
string
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Identification number (UUID) of the job

query Parameters
objectLimit
integer [ 1 .. 100 ]
Default: 100

Query parameter to change de default limitation of objects in the result data array

objectOffset
integer >= 0
Default: 0

Query parameter to change de default offset of objects in the result data array

filterFaxNumber
string

Query parameter to fetch recipients after his fax number

filterFaxNumberNorm
string

Query parameter to fetch recipients after his normed fax number

filterRecipientReference
string

Query parameter to fetch recipients after his recipient reference

filterInternationalDialingCode
string

Query parameter to fetch recipients after his international dialing code

filterResultCode
string

Query parameter to fetch recipients after his result code

filterResultText
string

Query parameter to fetch recipients after his result text

sortField
string
Enum: "faxNumber" "faxNumberNorm" "internationalDialingCode" "recipientReference" "fareZone" "senderTime"

Available sort options for the result data array.

sortOrder
string
Default: "asc"
Enum: "asc" "desc"

Describes the order for used sort fields

Responses

Request samples 

curl --output './jobRecipientsResponse.json' \
     --header 'X-Auth-Token: xxxx' \
     --header 'Content-Type: application/json' \
'https://service.fax-api.de/4.0/rest/jobs/{job-ID}/preview'

#use jq for pretty json output 
jq . jobRecipientsResponse.json

Response samples

Content type
application/json
{
  • "total": 100,
  • "offset": 0,
  • "count": 50,
  • "data": [
    ]
}

/jobs/{id}/preview

Description: To obtain the preview pdf document of a specific job

Authorizations:
ApiAuthKey
path Parameters
id
required
string
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Identification number (UUID) of the job

Responses

Request samples 

curl --output './jobRecipientsResponse.json' \
     --header 'X-Auth-Token: xxxx' \
     --header 'Content-Type: application/json' \
'https://service.fax-api.de/4.0/rest/jobs/{job-ID}/preview'

#use jq for pretty json output 
jq . jobRecipientsResponse.json

Response samples

Content type
application/json
{
  • "contentType": "application/pdf",
  • "content": "JVBERi0xLj***SVFT0YNCg=="
}

/jobs/{id}/templates

Description: To obtain a list of template documents to a specific job

Authorizations:
ApiAuthKey
path Parameters
id
required
string
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Identification number (UUID) of the job

Responses

Request samples 

curl --output './jobTemplatesResponse.json' \
     --header 'X-Auth-Token: xxxx' \
     --header 'Content-Type: application/json' \
'https://service.fax-api.de/4.0/rest/jobs/{job-ID}/templates'

#use jq for pretty json output 
jq . jobTemplatesResponse.json

Response samples

Content type
application/json
{
  • "total": 100,
  • "offset": 0,
  • "count": 50,
  • "data": [
    ]
}

/jobs/{id}/notifications

Description: To obtain a list of notifications to a specific job

Authorizations:
ApiAuthKey
path Parameters
id
required
string
Example: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Identification number (UUID) of the job

Responses

Request samples 

curl --output './jobNotificationsResponse.json' \
     --header 'X-Auth-Token: xxxx' \
     --header 'Content-Type: application/json' \
'https://service.fax-api.de/4.0/rest/jobs/{job-ID}/notifications'

#use jq for pretty json output 
jq . jobNotificationsResponse.json

Response samples

Content type
application/json
{
  • "total": 100,
  • "offset": 0,
  • "count": 50,
  • "data": [
    ]
}

Recipients

Contains resources to obtaining recipient information across all jobs

/recipients

Description: To obtain a list of recipients

Authorizations:
ApiAuthKey
query Parameters
objectLimit
integer [ 1 .. 100 ]
Default: 100

Query parameter to change de default limitation of objects in the result data array

objectOffset
integer [ 0 .. 5 ]
Default: 0

Query parameter to change de default offset of objects in the result data array

filterJobId
string

Query parameter to fetch after recipient related to specific fax job

filterSameAccount
boolean
Default: false

Query parameter to fetch recipient related to jobs linked to the used token/key for authorization

filterFaxNumber
string

Query parameter to fetch recipients after his fax number

filterFaxNumberNorm
string

Query parameter to fetch recipients after his normed fax number

filterRecipientReference
string

Query parameter to fetch recipients after his recipient reference

filterInternationalDialingCode
string

Query parameter to fetch recipients after his international dialing code

filterResultCode
string

Query parameter to fetch recipients after his result code

filterResultText
string

Query parameter to fetch recipients after his result text

sortField
string
Enum: "jobId" "faxNumber" "faxNumberNorm" "internationalDialingCode" "recipientReference" "fareZone" "senderTime"

Available sort options for the result data array.

sortOrder
string
Default: "asc"
Enum: "asc" "desc"

Describes the order for used sort fields

Responses

Request samples 

curl --output './recipientsResponse.json' \
     --header 'X-Auth-Token: xxxx' \
     --header 'Content-Type: application/json' \
'https://service.fax-api.de/4.0/rest/recipients'

#use jq for pretty json output 
jq . recipientsResponse.json

Response samples

Content type
application/json
{
  • "total": 100,
  • "offset": 0,
  • "count": 50,
  • "data": [
    ]
}

System

Contains resources to observe current health/state of API service

/health

Description: Checks health of the service

Responses

Request samples 

curl --output './healthResponse.json' \
     --header 'Content-Type: application/json' \
'https://service.fax-api.de/4.0/rest/health'

#use jq for pretty json output 
jq . healthResponse.json

Response samples

Content type
application/json
{
  • "status": true,
  • "version": "1.0.0"
}