Overview

The REST API provide programmatic access to read and write Ekopost data. Create a new campaign, envelope, scheduele print & distribution, and more. The REST API identifies applications and users using Basic Authentication; responses are available in JSON.

Format

The REST API is only using JSON; all requests body should be in JSON and all responses will be JSON. Make sure you set Request.Header.Content-Type to “application/json”.

Sample Request (RAW)

Content-Type: application/json; charset=UTF-8

Encoding

UTF8 is the encoding that should be used at all times.

Authorization

The API uses basic authorization, and all requests must be authorized at all times.

You can use a valid api-key or a base64 encoded string based on your user credentials to build the authorize header value. We recommend that you always use the api-key apprach over the base64 encoded string, as you can create/revoke/reactive/remove api-keys with ease while using the base64 approach your integrations may fail if the password of the used account would ever be changed.

Using an api-key (recommended)

Set the Request.Header.Authorization value to “api-key key”, to get your key you need to generate a new API key after you've signed in to your account, you'll be able to generate and manage your API keys from the account/api section.

Sample Request (RAW)

Authorization: api-key YiuyotGtRNDXik56lgq6
Content-Type: application/json; charset=UTF-8

Using a base64 string

Set the Request.Header.Authorization value to “Basic auth_token”, auth_token should be replaced with a base64 encoded string formatted like: "username:password", where username is your username and password is your password.

Sample Request (RAW)

Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

Error handling

All handled errors will result in bad request (code: 400) and the body will contain an error object for debugging and development purpose with further information how to validate the request, you can see a list of error codes in the section Error under Error code values.

Resources not found will result in not found (code: 404) and any unhandled exception will return internal error (code: 500).

Quick start

To send an envelope you must first create a campaign, then an envelope within that campaign, then create a content (read: upload a document/attachment) within that envelope, once this is done you'll have to close both the campaign and the envelope/s to mark them as ready for production, each envelope in the campaign will be printed & distributed as an individual postal item, the items will be printed & distributed on the campaign output date.

To schedule print and distribution of a envelope – follow these steps (all requests must be authorized).

• Create a campaign
  Creates an empty campaign in opened state.
• Create an envelope
  Creates an empty envelope in opened state for the specified campaign.
• Create content (document)
  Creates a new document and links it to the specified envelope.
• Create content (attachment)
  Creates a new attachment and links it to the specified envelope.
• Change the envelope state to closed
  Closes the envelope and marks it as ready for print and distribution. *Note* the campaign must also be closed.
• Change the campaign state to closed
  Closes the campaign and marks it and all related envelopes as ready for print and distribution.

Limitations

The Content object field named data must be a PDF version 1.4, support for later versions does exist, but printing quality nor result can not be guaranteed without testnig. We always recommend that you send your self a copy of the documents you'll be sending to inspect the result, any deviations should be reported to our support team.

Page margins & reserved areas

Download our content template to learn about our page margins, reserved page areas and where to place your destination adress and return adress for optimal visibility.

• Content teamplate for production in Sweden
• Document specifications for production in Sweden

Campaign

Campaigns allow for easy management of multiple envelopes and set a date when content should be distributed.

Create campaign

Creates a new campaign with state opened.

POST /campaigns

Request

Sample request

POST /campaigns HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
    "name": "Invoice March 2015",
    "output_date": "2015-06-01T12:00:00",
    "cost_center": "Finance Office"
}

Response

Sample response

HTTP/1.1 200 OK
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
    "id": "4ebeab48-ee03-474f-bc79-c6db082c2bad",
    "name": "Invoice March 2015",
    "output_date": "2015-01-01T12:00:00",
    "cost_center": "Finance Office",
    "envelope_count": 1,
    "state": "opened",
    "state_changed_at": "2015-01-01T12:00:00",
    "created_at": "2015-01-01T12:00:00"
}

Close campaign

Changes a campains state to closed and marks it and all related envelopes as ready for print & distribution.

POST /campaigns/{campaign_id}/close

Request

Sample request

POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/close HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

Response

Sample response

HTTP/1.1 200 OK

Cancel campaign

Changes a campains state to cancelled and marks it and all related envelopes as not ready for print & distribution.

POST /campaigns/{campaign_id}/cancel

Request

Sample request

POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/cancel HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

Response

Sample response

HTTP/1.1 200 OK

Get campaign

Gets a campaign.

GET /campaigns/{campaign_id}

Request

Sample request

GET /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

Response

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "id": "4ebeab48-ee03-474f-bc79-c6db082c2bad",
    "name": "Invoice March 2015",
    "output_date": "2015-01-01T12:00:00",
    "cost_center": "Finance Office",
    "envelope_count": 1,
    "state": "opened",
    "state_changed_at": "2015-01-01T12:00:00",
    "created_at": "2015-01-01T12:00:00" 
}

Get campaigns

Get a list of all campaigns created within a given timespan.

GET /campaigns?start{start}&stop={stop}&name={name}&state={state}

Request

Sample request

GET /campaigns?start={start}&stop={stop}&name={name}&state={state} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

Response

Sample response

The list will be in decending order based on the campaigns created_at date.

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[{
    "id": "4ebeab48-ee03-474f-bc79-c6db082c2bad",
    "name": "Invoice March 2015",
    "output_date": "2015-01-01T12:00:00",
    "cost_center": "Finance Office",
    "envelope_count": 1,
    "state": "opened",
    "state_changed_at": "2015-01-01T12:00:00",
    "created_at": "2015-01-01T12:00:00" 
}]

Envelope

Envelopes represents a single postal item that will be sent to a single recipient, an envelope can contain one document and several attachments.

Create envelope

Creates a new envelope with state opened linked to the specified campaign.

POST /campaigns/{campaign_id}/envelopes

Request

Sample request

POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
    "name": "Invoice 9923891",
    "address": null,
    "postage": "priority",
    "plex": "simplex",
    "color": true
}

Response

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "id": "f6aa0f0a-4514-46e5-be2c-539278a58e70",
    "name": "Invoice 9923891",
    "address": {
        "$type": "postal",
        "name": [
            "Company Inc.",
            "c/o John Doe"
        ],
        "street": [
            "Street no. 37"
        ],
        "postal_code": "65421",
        "city": "Gothenburg",
        "country": "SE"
    },
    "postage": "priority",
    "plex": "simplex",
    "color": true,
    "state": "opened",
    "state_changed_at": "2015-01-01T12:00:00",
    "created_at": "2015-01-01T12:00:00",
    "transaction" : {
            "state" : "completed",
            "state_changed_at" : "2015-01-01T12:00:00"
        }
}

Close evenlope

Changes an envelopes state to closed and marks it as ready for print & distribution.

POST /campaigns/{campaign_id}/envelopes/{envelope_id}/close

Request

Sample request

POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70/close HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

Response

Sample response

HTTP/1.1 200 OK

Cancel envelope

Changes an envelopes state to cancelled and marks it as not ready for print & distribution.

POST /campaigns/{campaign_id}/envelopes/{envelope_id}/cancel

Request

Sample request

POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70/cancel HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

Response

Sample response

HTTP/1.1 200 OK

Get envelope

Gets an envelope.

GET /campaigns/{campaign_id}/envelopes/{envelope_id}

Request

Sample request

GET /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

Response

Sample response

    HTTP/1.1 200 OK
    Content-Type: application/json; charset=UTF-8
    {
        "id": "f6aa0f0a-4514-46e5-be2c-539278a58e70",
        "name": "Invoice 9923891",
        "address": {
            "$type": "postal",
            "name": [
                "Company Inc.",
                "c/o John Doe"
            ],
            "street": [
                "Street no. 37"
            ],
            "postal_code": "65421",
            "city": "Gothenburg",
            "country": "SE"
        },
        "postage": "priority",
        "plex": "simplex",
        "color": true,
        "state": "opened",
        "state_changed_at": "2015-01-01T12:00:00",
        "created_at": "2015-01-01T12:00:00",
        "transaction" : {
            "state" : "completed",
            "state_changed_at" : "2015-01-01T12:00:00"
        }
    }

Get envelopes

Gets a list of all envelopes within a campaign.

GET /campaigns/{campaign_id}/envelopes?name={name}&state={state}

Request

Sample request

GET /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes?name={name}&state={state} HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

Response

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[{
    "id": "f6aa0f0a-4514-46e5-be2c-539278a58e70",
    "name": "Invoice 9923891",
    "address": {
        "$type": "postal",
        "name": [
            "Company Inc.",
            "c/o John Doe"
        ],
        "street": [
            "Street no. 37"
        ],
        "postal_code": "65421",
        "city": "Gothenburg",
        "country": "SE"
    },
    "postage": "priority",
    "plex": "simplex",
    "color": true,
    "state": "opened",
    "state_changed_at": "2015-01-01T12:00:00"
    "created_at": "2015-01-01T12:00:00",
    "transaction" : {
            "state" : "completed",
            "state_changed_at" : "2015-01-01T12:00:00"
        }
}]

Content

Content can either be a document or an attachment linked to an envelope, an envelope can only have one document linked to it, but several attachments, please read the section Limitation for further information.

Create content

Creates a content either as a document or attachment linked to the specified envelope, only one document can be linked to an envelope.

POST /campaigns/{campaign_id}/envelopes/{envelope_id}/content

Request

Sample request

POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70/content HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
    "data": "YW55IGNhcm5hbCBwbGVhcw==",
    "mime": "application/pdf",
    "length": 1024,
    "type": "document"
}

Sample request with return address

POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70/content HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
    "data": "YW55IGNhcm5hbCBwbGVhcw==",
    "mime": "application/pdf",
    "length": 1024,
    "type": "document",
    "return_address" : "true",
    "address": null (See Address objects postal for exampel when not null)
}

Response

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "id": "d2c5fedd-0749-482c-94b9-7f13bd442a04",
    "mime": "application/pdf",
    "length": 1024,
    "type": "document",             
    "return_address" : "false",
    "created_at": "2015-01-01T12:00:00"
}

Get content

Gets an envelope content.

GET /campaigns/{campaign_id}/envelopes/{envelope_id}/content/{content_id}

Request

Sample request

POST /campaigns/4ebeab48-ee03-474f-bc79-c6db082c2bad/envelopes/f6aa0f0a-4514-46e5-be2c-539278a58e70/content/d2c5fedd-0749-482c-94b9-7f13bd442a04 HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8

Response

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "id": "d2c5fedd-0749-482c-94b9-7f13bd442a04",
    "mime": "application/pdf",
    "length": 1024,
    "type": "document",
    "created_at": "2015-01-01T12:00:00"
}

Reachable

Through a reachable request you can figure out if a recipient is reachable or not and the true recipient address.

Check reachable status

Returns information if the recipient is reachable and the true recipient address.
Remarks: Returns 404 if the recipient is not reachable.

POST /reachable/{type}

Request

Sample request

GET /reachable/ebank/800101xxxx HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json; charset=UTF-8
{
    "recipient": "800101xxxx",
}

Response

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "recipient": "800101xxxx.BNK.SE",
}

HTTP/1.1 404 NOT FOUND
Content-Type: application/json; charset=UTF-8

Objects

This section describes all response objects within the REST API.

Campaign

Representation of a campaign that will be posted.

Object

{
    "id": "4ebeab48-ee03-474f-bc79-c6db082c2bad",
    "name": "Invoice March 2015",
    "output_date": "2015-01-01T12:00:00",
    "cost_center": "Finance Office",
    "envelope_count": 1,
    "state": "opened",
    "state_changed_at": "2015-01-01T12:00:00",
    "created_at": "2015-01-01T12:00:00"
}

State values

Envelope

Representation of an envelope that will be posted.

Object

{
    "id": "f6aa0f0a-4514-46e5-be2c-539278a58e70",
    "name": "Invoice 9923891",
    "address": {
        "$type": "postal",
        "name": [
            "Company Inc.",
            "c/o John Doe"
        ],
        "street": [
            "Street no. 37"
        ],
        "postal_code": "65421",
        "city": "Gothenburg",
        "country": "SE"
    },
    "postage": "priority",
    "plex": "simplex",
    "color": true,
    "state": "opened",
    "state_changed_at": "2015-01-01T12:00:00",
    "created_at": "2015-01-01T12:00:00",
    "transaction" : {
        "state" : "completed",
        "state_changed_at" : "2015-01-01T12:00:00"
    }
}

Postage values

Plex values

State values

Address

There are three valid types of addresses; postal, einvoice, email.

Object (postal)

The envelopes content will be printed and will be sent with regual postal mail.

{
    "$type": "postal",
    "name": [
        "Company Inc.",
        "c/o John Doe"
    ],
    "street": [
        "Street no. 37"
    ],
    "postal_code": "65421",
    "city": "Gothenburg",
    "country": "SE"
}

Object (email)

The envelopes content will be attached to an email and sent to the specified recipient.

{
    "$type": "email",
    "subject": "Invoice 9923891",
    "recipient": "johndoe@johndoe.com"
}

Object (einbox)

The content will be sent to a digital inbox (einbox) owned by the recipient, if the einbox doesn't exist the envelope will be printed and posted instead.

{
    "$type": "einbox",
    "subject": "Invoice 9923891",
    "recipient": "800101xxxx"
}

Object (einvoice)

The envelopes content will be transfered electronically to the recipient.

{
    "$type": "einvoice",
    "format": "svefaktura-1.0"
    "sender": "556838-4118",
    "sender_type": "SE.REGNO",
    "recipient": "556838-4118",
    "recipient_type": "SE.REGNO"
    "intermediator": null
}

Format values

Identifier values

Intermediator values

Object (ebank)

The envelopes content will be transfered electronically to the recipients internet bank.

{
    "$type": "ebank",
    "recipient": "5568384118.BNK.SE",
    "customer_number": "556838-4118",
    "customer_name": "No Ink AB",
    "invoice_number": "556838",
    "reference_type": "ocr",
    "reference_value": "0000556838411800",
    "giro_number": "5568-3841",
    "autogiro": true,
    "amount": 499.99,
    "invoice_date": "2015-01-01T00:00:00",
    "due_date": "2015-01-31T00:00:00"
}

Transaction

Object

The envelopes transaction information when it changed and to what state.

    "transaction" : {
        "state" : "completed",
        "state_changed_at" : "2015-01-01T12:00:00"
    }

Content

Representation of a document or an attachment that will be printed.

Object

{
    "id": 100,
    "mime": "application/pdf",
    "length": 1024,
    "type": "document",
    "created_at": "2015-01-01T12:00:00"
}

Type values

Error

Bad requests with http response code 400 does contains an error object with futher information about the bad request.

Object

{
    "error_code": "0",
    "error_message": "Invalid basic authentication token.",
	"developer_message": "Please verify that the account is activated and the username and password are valid."
}

Error code values

Tools

Package for .NET Framework

Ekopost is quick and easy to integrate in a .NET environment using our nuget package, the package uses a fluent interface to schedule print & production.

Installation

PM >  Install-Package Ekopost

Usage

using Ekopost;

/* Examples coming soon */
						

Sandbox

Set up Sandbox for testing

The url for connecting to our sandbox environment is http://api.sandbox.ekopost.se

Remarks:
Sandbox do not use https!
Nothing that uploaded to sandbox will be sent to end customers.

Getting started

1. Cretae a sandbox user. Click here to create.

2. If you already have created a sanbox-user, Click here to login

3. When you have created your sandbox account, you will automatically be signed in and you can immediately manually start uploading letter for testing or start using our API (http://api.sandbox.ekopost.se) with your user information that has been sent to your e-mail you entered when registering.