Introduction

Welcome to the eBrief API documentation!

Our API provides seamless integration for handling secure and efficient digital communication. Whether you're sending electronic letters, managing recipients, or tracking deliveries, our powerful and intuitive API makes it easy to automate workflows and enhance your document management processes.

What is eBrief?

eBrief.de transforms mailing into a seamless digital experience, enabling businesses and individuals to create and send letters online—without the hassle of printing. Whether for individual communication or high-volume mailings, our platform streamlines the entire process, making it faster, more cost-effective, and highly efficient. Recipients still receive traditional physical letters, while eBrief handles everything behind the scenes, from data processing to printing and delivery via PIN AG. 
eBrief provides a powerful API, so that businesses can fully automate their mailing workflows, integrating effortless letter dispatch into their existing systems.

eBrief API

The eBrief API is a modern RESTful interface designed to digitize and automate traditional mail workflows.

Purpose: The API enables seamless integration of eBrief's services into existing systems, allowing users to send physical letters by uploading digital documents directly from their applications. This automation enhances the mailing workflow, covering data processing, printing, and delivery.

 

General API Information:

  • RESTful Architecture: The eBrief API is designed following REST principles, allowing for straightforward integration into various systems.
  • Data Format: Communications with the API utilize JSON-formatted data for both requests and responses.
  • Endpoints: Specific endpoints are provided for actions such as uploading documents, tracking mail status, and managing account settings.

 

Target Audience:

  • Large Enterprises: Organizations managing substantial volumes of mail, such as hospitals, insurance companies, and financial institutions, can benefit from automating their outbound mail processes.
  • Software Developers: Developers seeking to incorporate mailing functionalities into their applications can leverage the API for efficient and reliable mail dispatch.

 

Key Use Cases:

  • Automated Bulk Mailings: Businesses can programmatically send large batches of documents, such as invoices, notices, or marketing materials, without manual intervention.
  • Personalized Communication: The API allows for the dynamic generation and dispatch of personalized letters, enhancing customer engagement.
  • System Integration: Companies can integrate the API with their CRM or ERP systems to automate routine correspondence, ensuring timely and consistent communication.

 

Why Use the eBrief API?

  • Scalability: Handle high volumes of digital correspondence with ease.
  • Security: Ensure secure communication with industry-leading encryption.
  • Automation: Streamline document workflows and reduce manual effort.
  • Flexibility: Integrate with your existing systems effortlessly.
  • Real-Time Tracking: Gain full visibility into document processing and delivery status.

By utilizing the eBrief API, organizations can reduce operational costs, improve efficiency, and maintain the reliability of traditional postal services through a digital interface. 

 

Key Features

  • Send eBriefs: Create and dispatch digital letters effortlessly.
  • Recipient Management: Store and manage recipient details.
  • Delivery Tracking: Monitor the status of your sent documents.
  • Webhooks & Callbacks: Get real-time updates on document processing.

Getting started

Requirements

  • Technical Expertise: Familiarity with RESTful API integration and handling JSON data is essential.
  • Development Environment: Set up an environment capable of making HTTPS requests and processing responses.
     

Account Setup

Contact eBrief support team to discuss your specific needs and initiate the account creation process. Provide our team with details about your company and intended use cases to facilitate account setup.
Once your account is created, you'll receive a confirmation email with your credentials needed to start using eBrief API.

Our API is available at the following URL:

Document Templates & Layouts

To ensure documents are processed and printed correctly, eBrief provides official print templates. Before submitting documents, please verify that your layout adheres to the required format.

Tip: Make sure that the recipient's address and barcode are positioned according to the template. Incorrect formatting may lead to processing delays.

If you need further assistance with setup or document formatting, contact eBrief support at:

Authentication

The eBrief API uses a Bearer Token for secure authentication. To access any protected endpoint, you first need to generate a Bearer Token using your API credentials. This token must be included in the Authorization header of all subsequent API requests.

 

Authentication Type: Basic Authentication (Username & Password required).
 

Use the Token:

For all API requests, include the token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Tip: 
Always keep your API credentials secure and avoid sharing your bearer token.                                                           
Make sure to renew the token before it expires after 7 days.

 

To generate the token: Use your basic authentication username/password provided by eBrief support

// The request must contain the Authorization header with base64 encoded username:password
{
  ...
  Headers: {
    Authorization: basic btoa(`${username}:${password}`)
    ...
  }
}

 

 

Generate BearerToken

GET
https://api.ebrief.de/oauth2/token/generateBearerToken

AuthenticationResponse

const username = "yourUsername";
const password = "yourPassword";

// Encode credentials in Base64
const headers = new Headers({
  "Authorization": "Basic " + btoa(`${username}:${password}`),
  "Content-Type": "application/json"
});

fetch("https://api.ebrief.de/oauth2/token/generateBearerToken", { method: "GET", headers })
  .then(response => {
    if (!response.ok) throw new Error(`HTTP error! Status: ${response.status}`);
    return response.json();
  })
  .then(({ GenerateBearerTokenResult }) => console.log("Success:", data))
  .catch((error) => console.error("Error:", error));

 

Validate BearerToken

The eBrief API provides an endpoint to verify if a Bearer Token is still valid. This ensures that your token remains active for secure API requests without unnecessary failures.

Send a Request:

  • Make a POST request to the endpoint.
  • In the request body, include the token as a JSON object without the Bearer prefix.

 

Tip: This endpoint is useful for pre-validating tokens before making resource requests, ensuring smoother workflows.

 

Validate Request

POST
https://api.ebrief.de/oauth2/token/validateToken
Request body

Token:

[required]stringYour_Token

ValidateResponse

<?php
$url = 'https://api.ebrief.de/oauth2/token/validateToken';
$token = 'your_bearer_token_here';

$data = json_encode(["Token" => $token]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);

$response = curl_exec($ch);
curl_close($ch);

echo "Response: " . $response;

Jobs

Authentication:
Before interacting with jobs, users must generate a Bearer token. 

Refer to Generate Bearer Token section to generate the token.

Job:

The job is a printing task where all the uploaded files, and generated documents are associated. The job's attributes define in what way the documents should be printed and some other extra parameters. Below is the usual lifecycle of each printing job. The lifecycle can be slightly different from case to case depending if there was an error or other unexpected events.

ActionStatusDescription
Create JobUNPROCESSED

The job is created and in the phase of uploading more files.

 

⚠️ The uploaded files it not a document yet. It is just a raw file, the documents are derived from uploaded file(s) in further steps

 

Upload filesUNPROCESSEDIn this phase user can upload as many files as desired to the printing job.
Commit a jobCOMMITTED

Now the files are accepted and commited for processing. In this phase eBrief will parse the files, read out the addresses and split them in to documents. After this step if you get the job by Id, you will see the generated documents.

 

⚠️ After this step you cannot add more files to the job

 

Review Uploaded DocumentsCOMMITTED

At the phase users are intended to get the job and see if the documents were generated correctly and if they all have expected status codes.

It is possible to delete the generated documents rom the job at this point, but still cannot add more documents to the job.

Distribute a jobDISTRIBUTEDAfter the distribution is done there is no more editing to the job. But it is still possible to interact with it to read the data, such as get the job, job's documents etc...
Simple Flowchart Ebrief.drawio.png

Jobs Webhook

eBrief allows external customers to use a webhook to monitor the Jobs status change events. For that the user should implement an endpoint to accept a POST Request with the body identical to the response of get job endpoint.
 

Contact eBrief Customer Support to provide your webhook url to start recieving the updates each time when submitted jobs change status.

 

Possible Job Statuses

Jobs in the eBrief API go through multiple stages during processing. Each status reflects the current state of a job, from document preparation to final distribution. Understanding these statuses helps in tracking job progress and managing exceptions effectively.

Below is a detailed explanation of each job status:

 

Initial Job Creation & Preparation

 
 UNPROCESSEDThe job is created, and processing has not yet started. You can still add documents to the job. Relevant When batching multiple files/documents for a single job. 
 
 
 COMMITTEDThe job is released for processing. No further documents can be added to the job. 
 
 
 

Document Preparation

 
 PROCESSING_DOCUMENTS_PREPAREDocuments within the job are being prepared.  This includes generating or converting PDFs. 
 
 
 COMPLETED_DOCUMENTS_PREPAREDocument preparation is complete. The job moves to the document processing phase. 
 
 
 

Document Processing

 
 PROCESSING_DOCUMENTS_PROCESSDocuments are being processed for printing. This includes address checks, barcode generation, and other enhancements. 
 
 
 COMPLETED_DOCUMENTS_PROCESSProcessing is complete.  Documents are now ready for user confirmation or distribution. 
 
 
 

User Interaction (If Required)

 
 USER_CONFIRMATION_REQUESTEDUser intervention is required. Some documents couldn't be fully processed and need review. 
 
 
 USER_WAIT_FOR_SHOPPINGThe user needs to confirm the job before it can be released for printing and distribution. 
 
 
 

Distribution & Printing

 
 DISTRIBUTION_READY_FORThe job is confirmed for distribution. Documents are ready for printing and enveloping. 
 
 
 DISTRIBUTION_COMPLETEDDocuments have been successfully transferred to the printing facility. Printing and enveloping will proceed. No further changes can be made to the job's documents. 
 
 
 

Billing & Finalization

 
 BILLING_COMPLETEDBilling data has been transferred to the ERP system for invoicing. 
 
 
 JOB_COMPLETEDThe job is fully finalized. No further updates will occur for this job. 
 
 
 Error Handling 
 ERROR_DOCUMENTOne or more documents in the job are erroneous.  Action is required to correct the issue before proceeding. 
 
 
 ERROR_GENERALA general error occurred during job processing. This may require user intervention or support assistance. 
 
 
 

Job Cancellation

 
 USER_DELETEDThe job was deleted by the user. It will not be printed, distributed, or invoiced. 
 
 
 ROLLEDBACKThe job has been rolled back, and documents will not be printed or sent. This status typically occurs when an error is detected before distribution. 
 
 

Attributes for processing

When processing documents for printing and distribution, several attributes can be specified to define the printing, handling, and delivery preferences. Some of the attributes show effect on the price. For more information refer to pricing tool. Below is a detailed explanation of each attribute and its usage.

 

⚠️ Attention: "string" type fields with value "false" are not boolean and should be used as a string "false"!

 

 

 

    
 

Printing Preferences

 
 IsDuplex (Default: false)

Defines if printing should be double-sided.

  • true: Print on both sides of the paper (duplex).
  • false: Print on one side only (simplex).
 
 
 
 IsColor (Default: false)

Specifies whether printing should be in color or black and white.

  • true: Print on both sides of the paper (duplex).
  • false: Print on one side only (simplex).
 
 
 
 

Distribution Preferences

 
 IsTracking (Default: false)

Enables tracking for the shipment after printing and enveloping.

  • true: Trackable shipment (different pricing applies).
  • false: No tracking.
 
 
 
 EnvelopeFormat

Specifies the envelope format. Only applicable if the document should be sent as C4 format, regardless of page count. 

  • Accepted value: "C4"
  • Leave empty if standard format is acceptable.
 
 
 
 Franking (Default: Interleaved 2/5)

Defines the type of barcode for franking.
Possible values:

  • 'tiny': DataMatrixCode
  • 'none': No barcode
  • (If not specified, the default barcode type will be Interleaved 2/5.)
 
 
 
 

Data Validation & Automation

 
 AdressCheck (Default: true)

Defines whether an address check should be performed. Verifies if the ZIP code and city match.

  • true: Perform address check (default).
  • false: Skip address check.
 
 
 
 SilentConfirm (Default: false)

Specifies whether the job should be automatically confirmed for printing without additional user intervention.

  • true: Silent confirmation.
  • false: Manual confirmation required.
 
 
 
 

Notifications

 
 NotificationMail

Allows for an email notification when the job distribution is completed.

Value: Any valid email address (e.g., "user@example.com").

 
 
 
 

Advanced Options (Contact eBrief Support Required)

 
 EnvelopeTypeUsed only after contacting eBrief support. Specifies a custom envelope type for special mailing requirements. 
 
 
 PaperTypeUsed only after contacting eBrief support. Defines the type of paper to be used for printing. 
 
 
 PageRemovalRegexUsed only after contacting eBrief support. Allows removal of specific pages from the document based on a regular expression. 
 
 
 DocumentsMergeRegexUsed only after contacting eBrief support. Merges multiple separate documents into one based on a defined pattern. 
 
 
 Tip: Carefully select the attributes based on your needs. For standard mailings, default values are usually sufficient, while advanced options should be coordinated with eBrief support. 

 

 

    // Reference

     "Attributes":  {  

        "IsDuplex": "false",

        "IsColor": "false",  

        "NotificationMail": "my.email@enterprise.com",  

        "IsTracking": "false"  

    }

 

Job Attachments

Attachments are the additional files to the job. These files will be also printed alongside with the documents and sent together with each document. Example use case is if you uploaded a file with 100 documents/letters and for each of these letters you want to attach a return note. Then you can add this return note within job's attachments property.

 

⚠️ Reminder - The attachments should be added to the job before commiting the job for processing.

 

Create New Job

Creates an empty job

This request creates an empty job. Files are then expected to be uploaded to the job. Job attributes define how documents are printed. Refer to Attributes.

 

⚠️ After you upload files to the job, you will need to commit and then distribute the job to send it for printing. Refer to Job Lifecylce

 

 

 

Create Job

POST
https://api.ebrief.de/jobs

The job is expected to be created with a status UNPROCESSED. The created job expectedly will not contain any file and document.

 

 

Request body
objectJob attributes and print options

Created Job

fetch("https://api.ebrief.de/jobs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_TOKEN"
  },
  body: JSON.stringify({
    Attributes: {
      IsDuplex: "false",
      IsColor: "false",
      NotificationMail: "my.email@enterprise.com",
      IsTracking: "false"
    }
  })
})
.then(res => res.json())
.then(data => console.log(data))
.catch(err => console.error(err));

Create a single-document Job

Creates a new job with a file containing a single document/letter

This request allows to create a job with a single uploaded file at once. The uploaded file should contain only one document/letter and it doesn't require to be confirmed and distributed in order to be proceeded for printing. When Job is created with this endpoint then it is going to be scheduled for printing right away. Expected job status after creating is BILLING_COMPLETED or DISTRIBUTION_COMPLETED both indicate that the job is scheduled for printing.

 

The request contains the attributes and all of the attributes are optional. When any of the attributes is not given then the default value will be used. To see the full list of possible attribute values refer to Job Attributes section.

 

⚠️ Attention: Since this is a single-document file there is not much to review and check. Jobs created with this endpoint won't have steps in lifecycle to preview and delete documents. The job is already scheduled for printing.

 

⚠️ Attention: You cannot upload more files to this job after creation.

 

Create a single-document job

POST
https://api.ebrief.de/jobs/singleFiles
Request body
objectMain document to be printed
arrayOptional additional documents or inserts
objectJob attributes and print options

Created Job

fetch('https://api.ebrief.de/jobs/singleFiles', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Document: {
      FileName: "eBrief-Template.pdf",
      FileContent: "ABCDEF"
    },
    Attachments: [],
    AddressInformation: null,
    Attributes: {
      IsDuplex: "false",
      IsColor: "false",
      NotificationMail: "my.email@enterprise.com",
      IsTracking: "false"
    }
  })
})
.then(response => response.json())
.then(data => console.log('Job created:', data))
.catch(error => console.error('Error:', error));

Create a page separated serial-document job

Creates a serial-document job separated with page number

Creates a job with initial serial-document file. The job is expected to be created with status UNPROCESSED. 
The uploaded file can contain multiple documents. But each document should have a fixed amount of pages. During processing the file is split to documents with this fixed amount of pages.

i.e. If you have a file with 10 pages where each 2 pages are a single letter then set the "PageNumber" attribute to 2

 

After creation the job should pass all the usual lifecycle of the job creation. Refer to Job lifecycle. You can then add more files to the job after creation using add files endpoints.

 

When all the desired files are uploaded the job must be commited for processing. During processing the uploaded files will be parsed, the addresses detected and documents created. 

 

⚠️Attention: Further steps to proceed the job for printing is explained in commit section.

 

⚠️Attention: If you want to skip manually commiting the job for processing then include in request body an attribute "SilentConfirm":  true. But then you won't be able to upload more files to the job.

 Attributes: {
  IsDuplex: "false",
  ...
  SilentConfirm: true,
  ...
}

Create Serial-Document Job Split By Page

POST
https://api.ebrief.de/jobs/splitOnFixedPageFiles
Request body

PageNumber

numberNumber of pages for each document/letter in uploading file. The uploaded file will be split to document/letters by this amount of pages.
objectMain document to be printed
arrayOptional additional documents/files. These will be attached to each document processed from the uploaded file
objectJob attributes and print options

Created Job

fetch('https://api.ebrief.de/jobs/splitOnFixedPages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    PageNumber: 1, // Each letter has 2 pages
    Document: {
      FileName: "eBrief-Template.pdf",
      FileContent: "ABCDEF"
    },
    Attachments: [],
    AddressInformation: null,
    Attributes: {
      IsDuplex: "false",
      IsColor: "false",
      NotificationMail: "my.email@enterprise.com",
      IsTracking: "false"
    }
  })
})
.then(response => response.json())
.then(data => console.log('Split job created:', data))
.catch(error => console.error('Error:', error));

Create a word separated serial-job

Creates a serial-document job separated by word

Creates a job with initial serial-document file. The job is expected to be created with status UNPROCESSED. 
The uploaded file can contain multiple documents. But each document should have a certain word as a mark to end a document. The file will be split to documents each time when this mark is found.

 

For the rest the behavior of the endpoint is identical to page-separated serial-document.


 

Create Serial-Document Job Split By Mark

POST
https://api.ebrief.de/jobs/splitOnMarkFiles
Request body

Mark

stringCustom mark or tag for identifying the end of the letter (e.g. Best Regards)
objectMain document to be printed
arrayOptional additional documents/files. These will be attached to each document processed from the uploaded file
objectJob attributes and print options

Created Job

fetch('https://api.ebrief.de/jobs/splitOnMarkFiles', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Mark: "Musterstadt",
    Document: {
      FileName: "eBrief-Template.pdf",
      FileContent: "ABCDEF"
    },
    Attachments: [],
    Attributes: {
      IsDuplex: "false",
      IsColor: "false",
      NotificationMail: "my.email@enterprise.com",
      IsTracking: "false"
    }
  })
})
.then(response => response.json())
.then(data => console.log('Split job created:', data))
.catch(error => console.error('Error:', error));

Add Single-Document file to existing job

The uploading file will be treated as Single-Document file

This request allows you to add more files to existing job. Each added job is processed with the attribute's of the existing job.
It is expected that you use this endpoint after creating single-document or serial-document job. But each file you upload must be indented to be processed with the same attributes. The uploaded file from this url will be treated as single-document without matter if the initially the job was created with single or serial document files.

 

⚠️ The "attachements" is not part of the job. They are part of each file. So if you need the attachments for uploading file then also include the attachments with the uploading file.

 

 

Add Single-Document file to the job

POST
https://api.ebrief.de/{jobId}/singleFiles
Path Params

jobId

[required]stringPreviously created job id
Request body
objectExtra file to be uploaded
arrayOptional attachments to the documents of this file

Updated Job

const jobId = 'YOUR_JOB_ID_HERE';

fetch(`https://api.ebrief.de/${jobId}/singleFiles`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Document: {
      FileName: "eBrief-Template.pdf",
      FileContent: "ABCDEF"
    }
  })
})
.then(response => response.json())
.then(data => console.log('File uploaded:', data))
.catch(error => console.error('Error:', error));

Possible Document Statuses

In eBrief the Documents are processed through certain events. It is possible to observe which events has the Document passed and what is it's status.

 

List of Document's statuses with explanation:

PREPARED The document is being prepared for processing
UNPROCESSED Processing not yet triggered for the document.
PROCESSED Document is converted into a PDF-File
MERGED If the attribute for merging documents is given, it happens in this situation
ADDRESS_EXTRACTED The address of the document is read and compared with the address database
WARNING_USER_INTERACTION_REQUIRED There were errors verifying the address. The user can ignore this error or exclude the affected documents from processing
BARCODE_COLLECTED A tracking number is reserved and attached to the document
ARTICLE_COLLECTED With the existing parameters such as number of pages, print properties, address, the corresponding article and price are determined
OK Document is successfully processed and waits for further distribution
USER_DELETED  Document was deleted by the user. Document is not printed and billed
USER_IGNORED User ignored the address verification warning
IN_DELIVERY The document is packed into a ZIP-file with print parameters (and other associated documents) for delivery to the print service provider
COMPLETED The whole process around the document for distributing is complete
 

Add page separated serial-document to job

Adds a serial-document file separated with page number

This request is used to upload more files to the existing job. The files must contain multiple letters with fixed amount of pages for each letter/document.

It is expected that you use this endpoint after creating single-document or serial-document job. But each file you upload must be indented to be processed with the same attributes. The uploaded file from this url will be treated as serial-document without matter if the initially the job was created with single or serial document files.

 

 

⚠️ The "attachements" is not part of the job. They are part of each document. So if you need the attachments for uploading file then also include the attachments with the uploading file. Then these attachments will be part of each generated document/letter from this file.

 

 

Add page-separated serial-document file to existing job

POST
https://api.ebrief.de/jobs/{jobId}/splitOnFixedPageFiles
Path Params

jobId

[required]stringExisting job id
Request body

PageNumber

numberNumber of pages for each document/letter or split point
objectFile to be processed into documents
arrayOptional additional attachments for each generated document/letter

Updated Job

const jobId = 'YOUR_JOB_ID_HERE';

fetch(`https://api.ebrief.de/jobs/${jobId}/splitOnFixedPageFiles`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Mark: "Musterstadt",
    Document: {
      FileName: "eBrief-Template.pdf",
      FileContent: "ABCDEF"
    },
    Attachments: [
      {
        FileName: "eBrief-attachment.pdf",
        FileContent: "ABCDEF"
      }
    ],
    AddressInformation: null,
  })
})
.then(response => response.json())
.then(data => console.log('Split job created:', data))
.catch(error => console.error('Error:', error));

Add word separated serial-document to job

Adds a serial-document file separated with certain word

This request is used to upload more files to the existing job. The files must contain multiple letters with a certain word finishing each letter. i.e. "Best Regards"

It is expected that you use this endpoint after creating single-document or serial-document job. But each file you upload must be indented to be processed with the same attributes. The uploaded file from this url will be treated as serial-document without matter if the initially the job was created with single or serial document files.

 

⚠️ The "attachements" is not part of the job. They are part of each document. So if you need the attachments for uploading file then also include the attachments with the uploading file. Then these attachments will be part of each generated document/letter from this file.

 

 

https://api.ebrief.de/jobs/{jobId}/splitOnMarkFiles
POST

Add word-separated serial-document file to existing job

Path Params

jobId

[required]stringExisting job id
Request body

Mark

stringThe word to indicate an end of the document/letter. i.e. "Best Regards"
objectFile to be processed into documents
arrayOptional additional attachments for each generated document/letter

Updated Job

const jobId = 'YOUR_JOB_ID_HERE';

fetch(`https://api.ebrief.de/jobs/${jobId}/splitOnMarkFiles`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Mark: "Musterstadt",
    Document: {
      FileName: "eBrief-Template.pdf",
      FileContent: "ABCDEF"
    },
    Attachments: [
      {
        FileName: "eBrief-Template.pdf",
        FileContent: "ABCDEF"
      }
    ]
  })
})
.then(response => response.json())
.then(data => console.log('Split job created:', data))
.catch(error => console.error('Error:', error));

Add attachment to job

Add more attachments to the job

This request allows you to add attachment to the previously created job's documents. It is expected to be used after creating single-document or serial-document job.

 

⚠️ Reminder: Attachments can be added only before commiting the job

 

⚠️ Reminder - Job's document is not the same as uploaded file. Each uploaded file is then processed into document/letter. So a single file can produce one or multiple documents. The uploaded attachments will be applied to all documents/letters currently in the job that are already processed form uploaded files. If you upload more files to this job then attachments wont be included in new documents.

 

 

Add attachment to job's documents

POST
https://api.ebrief.de/jobs/{jobId}/attachments
Path Params

jobId

[required]stringExisting job id
Request body
objectDocument or attachment file to upload

Updated Job

const jobId = 'YOUR_JOB_ID_HERE';

fetch(`https://api.ebrief.de/jobs/${jobId}/attachments`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Document: {
      FileName: "eBrief-Template.pdf",
      FileContent: "ABCDEF"
    }
  })
})
.then(response => response.json())
.then(data => console.log('Attachment uploaded:', data))
.catch(error => console.error('Error:', error));

Commit a job

This request is used to commit a job. When this request is called eBrief will parse the uploaded files and generate the documents/letters from the files. Since uploded files can contain more than one document/letters the amount of documents are not always the same as the amount of uploaded files.

 

⚠️ After this request you cannot add more files to the job.

 

Form here the processing of the uploaded files start. During processing the files are parsed, addressed detected and documents are generated. After the processing ended you will be able to check the generated documents of the job. When commited the job status will change to COMMITTED then eBrief starts processing and results in one of the following statuses.

USER_CONFIRMATION_REQUESTEDThere were errors during documents generation, some documents may have wrong addresses detected, so it needs to be manually confirmed. When this happened the error documents must be confirmed before distributing the job.
USER_WAIT_FOR_SHOPPINGAll the required actions are performed and Job is ready to distribute. From here you can get the job by id and see the list of prepared documents.

 

After reviewing the generated documents proceed to distribute a job to schedule it for printing.

 

Commit Job

PUT
https://api.ebrief.de/jobs/{jobId}
Path Params

jobId

[required]stringJob Id to commit

Commited Job

fetch("https://api.ebrief.de/jobs/{jobId}", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
})
.then(res => res.json())
.then(console.log);

Distribute Job

Schedules the job for printing and sending

Distributes a job to eBrief as ready-to-print job. When distribution is started it will change the job's status to DISTRIBUTION_READY_FOR. When distributed the job will be scheduled to print, fold and send out to the recipients.

 

⚠️ Attention: From this moment there is no more changes to the job and job documents. Though it is possible to check the job's status by using GET endpoints.

 

⚠️ Reminder: Alternatively you can use webhook to monitor the job's status changes.

 

 

Distribute Job

POST
https://api.ebrief.de/jobs/distribution
Request body
arrayList of job IDs to set distribution status for

Distributed Jobs

fetch('https://api.ebrief.de/jobs/distribution', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Ids: [100200300, 100200302, 100200304]
  })
})
.then(response => response.json())
.then(data => console.log('Distribution result:', data))
.catch(error => console.error('Error:', error));

Get Job Details By Id

Get Job By ID

GET
https://api.ebrief.de/jobs/{jobId}
Path Params

jobId

[required]stringexisting job id

Found Job

const jobId = 'YOUR_JOB_ID_HERE';

fetch(`https://api.ebrief.de/jobs/${jobId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
.then(response => response.json())
.then(data => console.log('Job details:', data))
.catch(error => console.error('Error:', error));

Search for jobs

Searches for jobs using certain filters

Search Jobs

POST
https://api.ebrief.de/searchJobDetails
Request body
arrayList of job statuses to filter by

DateFrom

stringStart date for filtering jobs (ISO 8601 format)

DateTo

stringEnd date for filtering jobs (ISO 8601 format)
objectPagination settings

Found Jobs

fetch('https://api.ebrief.de/searchJobDetails', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    JobStatus: ["BILLING_COMPLETED", "USER_WAIT_FOR_SHOPPING", "ERROR_DOCUMENT"],
    DateFrom: "2025-07-11T06:46:46.3739564+02:00",
    DateTo: "2025-07-14T10:23:46+02:00",
    Paging: {
      PageNumber: 1,
      PageSize: 200
    }
  })
})
.then(response => response.json())
.then(data => console.log('Search result:', data))
.catch(error => console.error('Error:', error));

Delete Job By Id

Deletes a job by given id

This request sets the status of the job to "USER_DELETED"

 

 

Delete Job By Id

DELETE
https://api.ebrief.de/{jobId}
Path Params

jobId

[required]stringId of the job to delete

Delete Job Result

const jobId = 'YOUR_JOB_ID_HERE';

fetch(`https://api.ebrief.de/${jobId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
.then(response => {
  if (!response.ok) throw new Error('Failed to delete job');
  return response.json();
})
.then(data => console.log('Job deleted:', data))
.catch(error => console.error('Error:', error));

Delete Multiple Jobs

Sets multiple jobs status to USER_DELETED at once

Delete Jobs

DELETE
https://api.ebrief.de/jobs
Request body
arrayList of job IDs to be deleted

Job Delete Response

fetch('https://api.ebrief.de/jobs', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Ids: [100200300, 100200302, 100200304]
  })
})
.then(response => response.json())
.then(data => console.log('Jobs deleted:', data))
.catch(error => console.error('Error:', error));

Get Job's Uploaded Files

Gets the uploaded files and their contents from the created job

 

 

Get Job Uploaded Files

GET
https://api.ebrief.de/{jobId}/originalFiles
Path Params

jobId

[required]stringExisting Job Id

Job Files Result

const jobId = 'YOUR_JOB_ID_HERE';

fetch(`https://api.ebrief.de/${jobId}/originalFiles`, {
 method: 'GET',
 headers: {
   'Authorization': 'Bearer YOUR_TOKEN_HERE'
 }
})
.then(response => response.json())
.then(data => console.log('Original files:', data))
.catch(error => console.error('Error:', error));

Get Job File By Id

Gets a single file by id

Get Job File Content

GET
https://api.ebrief.de/{jobId}/originalFiles/{fileId}
Path Params

jobId

[required]stringExisting Job Id

fileId

[required]stringExisting File Id

Found File Content

const jobId = 'YOUR_JOB_ID_HERE';
const fileId = 'YOUR_FILE_ID_HERE';

fetch(`https://api.ebrief.de/${jobId}/originalFiles/${fileId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
.then(response => response.json())
.then(data => console.log('Original file:', data))
.catch(error => console.error('Error:', error));

Document

Attention:

Before interacting with documents, users must create a job, upload files and let them be processed into documents.

Document:

  • Document is derived from uploaded file to the job
  • Each Document is then printed and sent as a letter.
  • Documents pass through certain events before being printed and sent as a letter.

Possible Document Events

In eBrief the document passes through certain events to be processed. Events are stored as a history of the document and can be viewed anytime using the corresponding endpoint.

 

List of Document Events:

DOCUMENT_CREATED Document is being prepared for processing
DOCUMENT_DELIVERED Document/Shipment was delivered (only for trackable shimpents)
DOCUMENT_IN_DELIVERY Document/Shipment in delivery (only for trackable shipments)
DOCUMENT_PRINTER_WRAPPED Document was printed and enveloped
DOCUMENT_PROCESSED Document is converted into a PDF-File
DOCUMENT_PROCESSING_ADDRESS_EXTRACTING Address of the document was extracted and read
DOCUMENT_REGISTERED_AT_SORTINGMACHINEZ Document/Shipment was registered at sortingcentre after printing and enveloping
DOCUMENT_SENT_BACK Document/Shipment was not deliverable
DOCUMENT_TRANSFERRED_TO_PARTNER Document/Shipment was given to shipment carrier
DOCUMENT_TRANSFERRED_TO_PRINTER Document was given to print service provider
 

Get Document By ID

Get document details if the document ID is known.

Get Job By Id

GET
https://api.ebrief.de/Docs/{doc_id}
Path Params

docId

[required]stringId of created Document

Document Details

const docId = 'YOUR_DOC_ID_HERE';

fetch(`https://api.ebrief.de/Docs/${docId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
.then(response => response.json())
.then(data => console.log('Document details:', data))
.catch(error => console.error('Error:', error));

Get Document Events

The history of the document in the system

Get Document Events

GET
https://api.ebrief.de/{doc_id}/events
Path Params

docId

[required]stringDocument ID

Document Events

const docId = 'YOUR_DOC_ID_HERE';

fetch(`https://api.ebrief.de/${docId}/events`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
.then(response => response.json())
.then(data => console.log('Document events:', data))
.catch(error => console.error('Error:', error));

Get Documents By Filters

Searches for documents with given filters

 

 

Search Documents

POST
https://api.ebrief.de/docs/searchDocDetails
Request body
arrayList of document statuses to filter

DocumentEvent

stringOptional event code filter

DocumentFileName

stringFile name to search for

IsTracking

booleanWhether tracking is enabled (can be null for all)

CustomerNumber

stringCustomer number assigned by eBrief, optional

DateFrom

stringStart date for filtering documents (ISO format)

DateTo

stringEnd date for filtering documents (ISO format)
objectPagination settings

Found Documents

fetch('https://api.ebrief.de/docs/searchDocDetails', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    DocumentStatus: ["OK", "WARNING_USER_INTERACTION_REQUIRED", "ERROR_GENERAL"],
    DocumentEvent: "",
    DocumentFileName: "StandartBrief.pdf",
    IsTracking: null,
    CustomerNumber: "D01032295",
    DateFrom: "2025-07-12T06:54:16.5231753+02:00",
    DateTo: "2025-07-15T10:23:46+02:00",
    Paging: {
      PageNumber: 1,
      PageSize: 200
    }
  })
})
.then(response => response.json())
.then(data => console.log('Document search result:', data))
.catch(error => console.error('Error:', error));

Get The File With Marked Area Of The Document

When the file is uploaded through the job, it is then processed into documents. Each document is expected to contain an area with address information of the recipient. This request allows to fetch the marked file to check if the address was detected from the correct area.

 

 

Get Marked File

GET
https://api.ebrief.de/docs/{docId}/fileWithMark
Path Params

docId

[required]stringDocument's ID

Marked File

const hostname = 'https://api.ebrief.de';
const docId = 'YOUR_DOC_ID_HERE';

fetch(`${hostname}/docs/${docId}/fileWithMark`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
.then(response => response.json())
.then(data => console.log('File with mark:', data))
.catch(error => console.error('Error:', error));

Get Processed PDF File

This request is used to see the processed PDF document from uploaded file.

 

 

Get Processed File

GET
https://api.ebrief.de/{doc_id}/processedFile
Path Params

docId

[required]stringDocument ID

Processed File

const hostname = 'https://api.ebrief.de';
const docId = 'YOUR_DOC_ID_HERE';

fetch(`${hostname}/${docId}/processedFile`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
.then(response => response.json())
.then(data => console.log('Processed file:', data))
.catch(error => console.error('Error:', error));

Delete Document

Sets the documents' status to "USER_DELETED"

Delete Document

DELETE
https://api.ebrief.de/docs
Request body
arrayList of document IDs to be deleted

Deleted Documents

fetch('https://api.ebrief.de/docs', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Ids: [100200312, 100200315, 100200318]
  })
})
.then(response => response.json())
.then(data => console.log('Documents deleted:', data))
.catch(error => console.error('Error:', error));

Confirm Document

Use this request when the document is stuck at status "WARNING_USER_INTERACTION_REQUIRED" to move it to the status "USER_IGNORED". Then the document will be proceeded to in the process pipeline and distributed to printing and sending with assumption that the address is correct, but ony eBrief API failed to read out the address.

 

 

Confirm Document

POST
https://api.ebrief.de/docs/confirmation
Request body
arrayList of document IDs to confirm delivery or processing

Updated Documents

fetch('https://api.ebrief.de/docs/confirmation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Ids: [100200312, 100200315, 100200318]
  })
})
.then(response => response.json())
.then(data => console.log('Confirmation result:', data))
.catch(error => console.error('Error:', error));

Prices

Use this request to check the price for the shipment with pre-defined attributes.

 

 

Prices

POST
https://api.ebrief.de/prices
Request body

Amount

numberNumber of letters/documents to price
objectPricing attributes for the job

Prices

fetch('https://api.ebrief.de/prices', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    Amount: 1,
    Attributes: {
      Pages: 1,
      IsDuplex: false,
      IsColor: false,
      IsTracking: false,
      PaperType: "",
      EnvelopeType: "",
      EnvelopeFormat: "C4",
      RecycledPaper: false,
      Region: "National"
    }
  })
})
.then(response => response.json())
.then(data => console.log('Price calculation:', data))
.catch(error => console.error('Error:', error));

Statistics By Invoiced Articles

Articles are the invoicing units. Not all the documents and all the attributes are invoiced, so some of them are free. Besides attributes and documents there are also some other base fees for such as printing and etc... they will be also counted as article of each invoice. You can see the articles by created job, or all articles in certain time period.

In this request you can get the statistics articles for chosen time period.

 

 

Statistics By Articles

POST
https://api.ebrief.de/statistics/articles
Request body

CustomerNumber

stringCustomer number assigned by eBrief

DateFrom

stringStart date for statistics period (ISO format)

DateTo

stringEnd date for statistics period (ISO format)

Found Articles

fetch('https://api.ebrief.de/statistics/articles', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    CustomerNumber: "D012345",
    DateFrom: "2025-07-09T00:00:00+02:00",
    DateTo: "2025-07-16T00:00:00+02:00"
  })
})
.then(response => response.json())
.then(data => console.log('Statistics result:', data))
.catch(error => console.error('Error:', error));

Statistics Of Articels By Job

Use this request to see the articles generated for the job by jobId.

 

 

Job Articles

GET
https://api.ebrief.de/statistics/articles/{jobId}
Path Params

jobId

[required]stringExisting Job Id

Found Articles

const jobId = 'YOUR_JOB_ID_HERE';

fetch(`https://api.ebrief.de/statistics/articles/${jobId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  }
})
.then(response => response.json())
.then(data => console.log('Article statistics by job:', data))
.catch(error => console.error('Error:', error));

Statistics Of Jobs By Statuses

Jobs Articles

POST
https://api.ebrief.de/statistics/jobs
Request body

CustomerNumber

stringCustomer number assigned by eBrief

DateFrom

stringStart date for statistics period (ISO format)

DateTo

stringEnd date for statistics period (ISO format)

Jobs Statistics

fetch('https://api.ebrief.de/statistics/jobs', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    CustomerNumber: "D012345",
    DateFrom: "2025-07-09T00:00:00+02:00",
    DateTo: "2025-07-16T00:00:00+02:00"
  })
})
.then(response => response.json())
.then(data => console.log('Job statistics:', data))
.catch(error => console.error('Error:', error));

Documents Statistics

Documents Statistics

POST
https://api.ebrief.de/statistics/documents
Request body

CustomerNumber

stringCustomer number assigned by eBrief

DateFrom

stringStart date for statistics period (ISO format)

DateTo

stringEnd date for statistics period (ISO format)

Statistics

fetch('https://api.ebrief.de/statistics/documents', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_TOKEN_HERE'
  },
  body: JSON.stringify({
    CustomerNumber: "D012345",
    DateFrom: "2025-07-09T00:00:00+02:00",
    DateTo: "2025-07-16T00:00:00+02:00"
  })
})
.then(response => response.json())
.then(data => console.log('Document statistics:', data))
.catch(error => console.error('Error:', error));