Sign in
     
Ekopost API
a thorough description of our API, from how to authorize to create and schedule an envelope for print & distribution, and more.

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.

Package for .NET Framework available

If you're using .NET Framework you can download and install our nuget package directly, see the section Tools for more information.

Sandbox - For Developers

During development and testing we recommend using our Sandbox Environment, see the section Sandbox for more information.

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;
Copy

Encoding

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

Authorization

The API supports basic, api-key and Oauth2 client credentials authorization, and all requests must be authorized at all times.

You can use a valid api-key, bearer token 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 or Oauth2 approach over the base64 encoded string, 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

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
Copy

Using Oauth2 with client credentials

First contact hejsan@ekopost.se to request a client_id and a client_secret

When customer has a client_id and a client_secret, these need to be base64 encoded and sent to the API via POST to receive an access token which is used for subsequent calls. The base64 encoded string should be created from a string formatted like: "client_id:client_secret".

Create the base64 encoding to be used, replace client_id and client_secret with real values and make sure there are no trailing newlines and that the string is encoded literally

Then set the Request.Header.Authorization value to “Basic base64encodedString

Sample Request (RAW)

POST https://api.ekopost.se/auth Authorization: Basic dXNlcm5gaGO6cGFzc3dvctE= Content-Type: application/json; charset=UTF-8
Copy

Sample response

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "access_token": "INKJ8ABgVeNIcp9MsuTIXO8QJtBiFE677h2hgcB1USVIY8KadBJ_faNrdKulFs", "token_type": "bearer", "expires_in": 28800 }
Copy

An access_token is valid for up to 8 hours. A new access_token can be requested any time. If a request to the API is issued with a non valid access_token a http-response with the HTTP-header 401 is returned such as HTTP/1.1 401 Unauthorized. With the use of a valid access_token request to the API can be done as the example below.

Sample Request with bearer (RAW)

Authorization: Bearer INKJ8ABgVeNIcp9MsuTIXO8QJtBiFE677h2hgcB1USVIY8KadBJ_faNrdKulFs Content-Type: application/json; charset=UTF-8
Copy

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
Copy

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 testing. 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.

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

BODY
Parameter Type Description
name String A friendly name to identify the campaign.
output_date Date Date in UTC format representing the date when you would like your envelope printed & distributed.
cost_center String Value representing an internal cost center.
signing Boolean Optional Set to true if it is a digital agreement

Sample Request (RAW)

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" }
Copy

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

URL
Parameter Type Description
campaign_id Guid Guid that represents the specified campaign of which to change state to closed.

Sample Request

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

Response

Sample response

HTTP/1.1 200 OK
Copy

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

URL
Parameter Type Description
campaign_id Guid Guid that represents the specified campaign of which to change state to cancelled.

Sample Request

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

Response

Sample Response

HTTP/1.1 200 OK
Copy

Get campaign

Gets a campaign.

GET/campaigns/{campaign_id}

Request

URL
Parameter Type Description
campaign_id Guid Unique id of the campaign to retrieve.

Sample Request

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

Response

BODY
Parameter Type Description
id Guid The campaign object's unique id.
name String A friendly name to identify the campaign.
output_date Date Date in UTC format representing the date when you would like your envelope printed & distributed.
cost_center String Value representing an internal cost center.
envelope_count Int Value representing the total number of envelopes in the campaign.
state String State type denominator, see the section State values for valid values.
state_changed_at Date Date in UTC format representing the date when the campaign state was changed.
created_at Date Date in UTC format representing the date when the campaign was created.

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" }
Copy

Get campaigns

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

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

Request

URL
Parameter Type Description
start Date Optional Date in UTC format representing the start of a timespan.
Remarks: Default value if not specified is today.
stop Date Optional Date in UTC format representing the stop of a timespan.
Remarks: Default value if not specified is tomorrow.
name String Optional Name of the requested campaign.
state String Optional State type denominator, see the section State values for valid values.

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
Copy

Response

BODY
Parameter Type Description
Array An array of all Campaigns found within the given timespan.

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" }]
Copy

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

URL
Parameter Type Description
campaign_id Guid Unique id of a campaign within which to create the envelope.

BODY
Parameter Type Description
name String A friendly name to identify the envelope.
address Object Address object that represents the destination, see the section Address objects for valid formats.
Remark: In the case of a postal address, the address needs to be embedded into the uploaded document. The one exception to an embedded address is when the flag 'use_coverpage' is lit on the postal address object. A 'null' value will be treated as an address of type postal.
postage String Postage type denominator, see the section Postage values for valid values. Remark: For customers registered to our Norwegian production site, this parameter can be considered redundant as it is ignored.
plex String Plex type denominator, see the section Plex values for valid values.
color Boolean Print the content in color (CMYK), if set to false the content will be printed in black and white.
pu Boolean Personal delivery, additional service for REK
kb Boolean Delivery receipt, additional service for REK
consignor_contact String Email for integration with the PostNord-app and receipt mail, additional service for REK
agent String Optional For use when agent
unique_id String Optional Use with an external id to prevent duplication. Is per customer.

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 }
Copy

Response

BODY
Parameter Type Description
id Guid The envelope object's unique id.
name String A friendly name to identify the envelope.
address Object Address object that represents the destination, see the section Address objects for valid formats. Remark: In the case of a postal address, the address needs to be embedded into the uploaded document. The one exception to an embedded address is when the flag 'use_coverpage' is lit on the postal address object. A 'null' value will be treated as an address of type postal.
postage String Postage type denominator, see the section Postage values for valid values.
plex String Plex type denominator, see the section Plex values for valid values.
color Boolean Print the content in color (CMYK), if set to false the content will be printed in black and white.
state String State type denominator, see the section State values for valid values.
state_changed_at Date Date in UTC format representing the date when the envelope state was changed.
created_at Date Date in UTC format representing the date when the envelope was created.
transaction Object Transaction object that the state of the Envelop Transaction object.
warning String Is in response if address is missing. If address is of type postal and the postal address not is complete an extra cost is added.
pu Boolean Personal delivery, additional service for REK
kb Boolean Delivery receipt, additional service for REK
consignor_contact String Email for integration with the PostNord-app and receipt mail, additional service for REK
agent String When agent is used
unique_id String When uniqueId is used.
failed_reason String May contain info if state is failed.

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", "use_coverpage": false }, "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" }, "pu": false, "kb": false, "consignor_contact": null }
Copy

Close envelope

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

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

Request

URL
Parameter Type Description
campaign_id Guid Unique id of a campaign.
envelope_id Guid Unique id of an envelope within the campaign.

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
Copy

Response

Sample response

HTTP/1.1 200 OK
Copy

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

URL
Parameter Type Description
campaign_id Guid Unique id of a campaign.
envelope_id Guid Unique id of an envelope within the campaign.

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
Copy

Response

Sample response

HTTP/1.1 200 OK
Copy

Get envelope

Gets an envelope. See webhook alternative to get status for envelopes.

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

Request

URL
Parameter Type Description
campaign_id Guid Unique id of a campaign.
envelope_id Guid Unique id of an envelope within the campaign.

Get failed envelopes

Gets an failed envelope. Typically used to find out failed reason for rescheduled envelopes

GET/campaigns/{campaign_id}/envelopes/{envelope_id}?state=failed

Request

URL
Parameter Type Description
campaign_id Guid Unique id of a campaign.
envelope_id Guid Unique id of an envelope within the campaign.
state String Optional State type denominator, see the section State values for values. Valid here are state failed

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
Copy

Response

BODY
Parameter Type Description
id Guid The envelope object's unique id.
name String A friendly name to identify the envelope.
address Object Address object that represents the destination, see the section Address objects for valid formats.
postage String Postage type denominator, see the section Postage values for valid values.
plex String Plex type denominator, see the section Plex values for valid values.
color String Print the content in color (CMYK), if set to false the content will be printed in black and white.
state String State type denominator, see the section State values for valid values.
state_changed_at Date Date in UTC format representing the date when the envelope state was changed.
created_at Date Date in UTC format representing the date when the envelope was created.
transaction Object Transaction object that the state of the Envelop Transaction object.
tracking Object If the envelope is a registered letter and is registered it will contain trackinginformation with parcelNo, trackingState and trackingUrl.
warning String Is in response if address is missing. If address is of type postal and the postal address not is complete an extra cost is added.

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" }, "tracking": { "tracking_state": "Init", "track_url": https://tracking.postnord.com/se/?id=RRXXXXXXXXSE, "parcel_no": RRXXXXXXXXSE " } }
Copy


Tracking states

(Only available for mailings with PostageType REK)

Init Created, not booked yet INFORMED Booked at Post Nord but not sent yet EN_ROUTE Sent and on its way to the delivery service point AVAILABLE_FOR_DELIVERY Delivered to the delivery service point and ready to be collected RETURNED Has been returned DELIVERED Has been delivered/collected DoneReturned After RETURNED, we send a notification mail to the user who created the mailing. Done After DELIVERED we send a notification mail to the user who created the mailing. After the states Done or DoneReturned the tracking of the mailing stops.
Copy

Get envelopes

Gets a list of all envelopes within a campaign.

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

Request

URL
Parameter Type Description
campaign_id Guid Unique id of a campaign.
name String Optional Name of the envelope or envelopes.
state String Optional State type denominator, see the section State values for valid values.

Get failed envelopes

Gets a list of all failed envelopes within a campaign. Typically used to find fail reason for original address object when envelope has been rescheduled

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

Request

URL
Parameter Type Description
campaign_id Guid Unique id of a campaign.
name String Optional Name of the envelope or envelopes.
state String Optional State type denominator, see the section State values for valid values.
address_type String Optional Address.$type, see Address objects for $type values. Valid here are ebank, einbox, einboxKivra and email.

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
Copy

Response

URL
Parameter Type Description
Array An array of all Envelopes within the campaign.

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" } }]
Copy

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

URL
Parameter Type Description
campaign_id Guid Unique id of a campaign within which the envelope exists.
envelope_id Guid Unique id of an envelope to add the content to.

BODY
Parameter Type Description
data String The original file's data as a base64encoded string.
mime String The original file's mime type.
length Int The original file's size in bytes.
type String Content type denominator, see the Type values section for valid values.
return_address Boolean Optional Set as true to add a return address on the upper left corner of the letter. (The address that will show is the return address on your account.)
address Object Optional Address object that represents postal destination of returned letters, see the section Address objects. Object (postal) is the valid object.
Remark: For this address to be used as a return address on the letter, return_address must also have the value 'true'

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" }
Copy

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) }
Copy

Response

BODY
Parameter Type Description
id Guid The content object's unique id.
mime String The original file's mime type.
length Int The original file's size in bytes.
type String Content type denominator, see the Type values section for valid values.
created_at Date Date in UTC format representing the date when the content was created.
return_address Boolean Value to show if return address was triggered..

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" }
Copy

Get content

Gets an envelope content.

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

Request

URL
Parameter Type Description
campaign_id Guid Unique id of a campaign.
envelope_id Guid Unique id of an envelope within the campaign.
content_id Guid Unique id of a content within the envelope.

Sample request

GET /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
Copy

Response

BODY
Parameter Type Description
id Guid The content object's unique id.
mime String The original file's mime type.
length Int The original file's size in bytes.
type String Content type denominator, see the Type values section for valid values.
created_at Date Date in UTC format representing the date when the content was created.

Sample request

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" }
Copy

EDI - Invoice integration

This section describes how to register a new sender, create invites and see the status of those invites.

Create sender

Creates a new sender

POST/edi/sender

Request

URL
Parameter Type Description

BODY
Parameter Type Description
Name String The sender's company name.
Address1 string The first address line of the sender.
Address2 string The second address line of the sender.
Zip_Code string The zip code of the sender.
City string The city of the sender.
Country_Code string The country code of the sender.
Contact_Name string The contact name of the sender.
Phone string The phone of the sender.
Email string The email of the sender.
CIN string The corporate identity number (org no) of the sender of an EDI invoice.
GLN string The global location number of the receiver of an EDI invoice.
VAT string The VAT of the sender.
Bank_Giro string The bankgiro of the sender.
Plus_Giro string The plusgiro of the sender.
IBAN string The IBAN of the sender.
BIC string The BIC of the sender.

Sample request

POST /edi/sender HTTP/1.1 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json; charset=UTF-8 {"Name":"Company Inc", "Address1":"Street no. 37", "Address2":"", "Zip_Code":"65421", "City":"Gothenburg", "Country_Code":"SE", "Contact_Name":"John Doe", "Phone":"+4670010020", "Email":"john.doe@companyinc.com", "CIN":"800101xxxx", "GLN":"7380000000000", "VAT":"SE543210123401", "Bank_Giro":"xxx-xxxx", "Plus_Giro":"xxxxxxx-x", "IBAN":"SExxxx.....", "BIC":"ESSE...."}
Copy

Response

BODY
Parameter Type Description
message string The status message of the request

Sample response

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message":"New sender 'Company Inc' registered" }
Copy

EDI Invitations

Get a list of sent invitation and their statuses

GET/edi/invitations

Request

URL
Parameter Type Description

BODY
Parameter Type Description

Sample request

GET /edi/invitations HTTP/1.1 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json; charset=UTF-8
Copy

Response

BODY
Parameter Type Description
ReceiverCin string ReceiverCin
ReceiverGln string ReceiverGln
DateSent string The date when the invitation was sent
Status string The status code of the invitation

Sample response

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 [{"ReceiverCin":"800101xxxx", "ReceiverGln":"7380000000000", "DateSent":"2023-01-17T00:00:00+01:00", "Status":"1002"}, {"ReceiverCin":"800101xxxx", "ReceiverGln":"7390000000000", "DateSent":"2023-01-18T00:00:00+01:00", "Status":"1001"}]
Copy

Status codes

registered = 1001,
sent = 1002,
received = 1003,
answered = 1004,
connection_approved = 1005,
connection_denied = 1006,
reminder_sent = 1007,
insufficient_information = 1008,
unkown_status = 1009,
expired = 1010

Update and get a list of sent invitation and their statuses

GET/edi/update-status

Request

URL
Parameter Type Description

BODY
Parameter Type Description

Sample request

GET /edi/update-status HTTP/1.1 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json; charset=UTF-8
Copy

Response

BODY
Parameter Type Description
ReceiverCin string ReceiverCin
ReceiverGln string ReceiverGln
DateSent string The date when the invitation was sent
Status string The status code of the invitation

Sample response

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 [{"ReceiverCin":"800101xxxx", "ReceiverGln":"7380000000000", "DateSent":"2023-01-17T00:00:00+01:00", "Status":"1002"}, {"ReceiverCin":"800101xxxx", "ReceiverGln":"7390000000000", "DateSent":"2023-01-18T00:00:00+01:00", "Status":"1001"}]
Copy

Reachable

Through a reachable request you can figure out if a recipient is reachable or not.

Check reachable status

Remarks: Returns 404 if the recipient is not reachable.

Remarks: Returns 200 and echoes the recipient parameter if the recipient is reachable.

POST/reachable/{type}

Request

URL
Parameter Type Description
type String The type of address to check reachable status for, valid values are 'einbox', 'ebank', 'einvoice' and 'mastercard'.

BODY
Parameter Type Description
recipient String The search parameter used to check reachable status.
sender String Optional FUI or tenantKey, id to use instead of default.

Sample request

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

Response

BODY
Parameter Type Description
recipient String Indicates success. A recipient has been found.

Sample request

POST /reachable/einbox HTTP/1.1 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json; charset=UTF-8 { "recipient": "19800101xxxx" }
Copy

Response

BODY
Parameter Type Description
recipient String Indicates success. A recipient has been found.

Sample request - multiple

POST /reachable/einbox HTTP/1.1 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json; charset=UTF-8 { "recipient": "19800101xxxx, 19810101xxxx, 19802101xxxx" }
Copy

Response

BODY
Parameter Type Description
recipients List Indicates success. Recipients has been found.
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "recipients": [ { "recipient": "19800101xxxx" }, { "recipient": "19810101xxxx" }, { "recipient": "19820101xxxx" } ] }

Sample request

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

Sample request

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

Check ebank list status

Remarks: Returns 404 if the recipient is not reachable.

Remarks: Returns 200 and echoes the recipient parameter if the recipient is reachable.

POST/reachable/ebank_list

Request

URL
Parameter Type Description
sender String The FUI to get ebank receivers for.

Sample request

POST /reachable/ebank HTTP/1.1 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json; charset=UTF-8 { "sender": "0000001.000002.SEB.SE", }
Copy

Response

BODY
Parameter Type Description
recipient Array An arry of all receivers

Sample response

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 [ { "identifier": "19800101xxxx", "address": "19800101xxxx.BNK.SE", "reachable": true }, { "identifier": "19830704xxxx", "address": "19830704xxxx.BNK.SE", "reachable": true } ]
Copy

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

Check guardians from ssn

POST/reachable/guardian

Request

URL
Parameter Type Description
recipient String The SSN to get guardian receivers for.

Sample request

POST /reachable/guardian HTTP/1.1 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json; charset=UTF-8 { "recipient": "YYYYMMDDXXXX", }
Copy

Response

BODY
Parameter Type Description
address_guardians Array An array of all receivers consists of recipient that includes SSN if reachable in digital mail box and postal address.

Sample response

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 [ { "recipient": "YYYYMMDDXXXX", "address_postal": { "name": [ "Petra Malstroem-Trell" ], "street": [ "MOSSTIGSVAGEN 9" ], "postal_code": "17238", "city": "GOTEBORG", "country": "SE" } }, { "recipient": "", "address_postal": { "name": [ "Petter Klas Flygmann" ], "street": [ "MOSSTIGSVAGEN 9" ], "postal_code": "17238", "city": "GOTEBORG", "country": "SE" } } ]
Copy

Peppol lookup

Check if recipient is in Peppol network with generic search

POST/reachable/peppol

Request

BODY
Parameter Type Description
Recipient String Search string. Fx. name, organisation number or VAT number

Sample request

POST /reachable/peppol HTTP/1.1 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json; charset=UTF-8 { "recipient": "ekopost ab" }
Copy

Response

Return list of "mathes" from the peppol network for more information see: https://directory.peppol.eu/public/locale-en_US/menuitem-docs-rest-api

Sample response

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 [ { "participantID":{ "scheme":"iso6523-actorid-upis", "value":"0007:559281xxxx" }, "docTypes":[ { "scheme":"busdox-docid-qns", "value":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1" }, { "scheme":"busdox-docid-qns", "value":"urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1" } ], "entities":[ { "name":[ { "name":"Ekopost AB" } ], "countryCode":"SE", "geoInfo":"Box 63, \r\nLandskrona, \r\n261 22, \r\nSE" } ] } ]
Copy

Check Einvoice Complience

Determines whether the setup of Einvoice sendouts is complete. Provides an error messages for various missing setup steps on non-success

POST/reachable/einvoiceready

Request

BODY
Parameter Type Description
ReceiverCin String The corporate identity number (org no) of the sender of an EDI invoice.
SenderCin String The corporate identity number (org no) of the sender of an EDI invoice.
ReceiverGln String The global location number of the receiver of an EDI invoice.
SenderGln String The global location number of the sender of an EDI invoice.

Sample request

POST /reachable/einvoiceready HTTP/1.1 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json; charset=UTF-8 { "ReceiverCin": "800101xxxx", "SenderCin": "800102xxxx" }
Copy

Response

BODY
Parameter Type Description
ReceiverCin String An echo of the input parameter.
SenderCin String An echo of the input parameter.
ReceiverGln String An echo of the input parameter.
SenderGln String An echo of the input parameter.
Success Boolean A 'true' result indicates that the setup process for einvoice sendouts is complete.
ErrorMessage String A message describing any required missing steps regarding einvoice setup.

Sample response

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "ReceiverCin": "800101xxxx", "SenderCin": "800102xxxx", "Success": true, "ErrorMessage": "" }
Copy

Check Mastercard reachability

Remarks: Returns 404 if the recipient is not reachable.

Remarks: Returns 200 and echoes the recipient parameter if the recipient is reachable.

POST/reachable/mastercard

Request

URL
Parameter Type Description
first_name String The first name of the recipient.
last_name String The last name of the recipient./td>
street_address1 String The street address, first line, of the recipient.
street_address2 String The street address, second line, of the recipient.
city String The city of the recipient.
zip_code String The zip code of the recipient.
country_code String The country code of the recipient.
phone_number String The phone number of the recipient. (+XX...)
email String The email address of the recipient.
birth_date String The birth date of the recipient.
ssn String The social security number of the recipient.

Sample request

POST /reachable/mastercard HTTP/1.1 Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ= Content-Type: application/json; charset=UTF-8 { "first_name": "Test", "last_name": "Person", "street_address1": "Street 1", "city": "Oslo", "zip_code": "0123", "ssn": "11223344556" }
Copy

Response

BODY
Parameter Type Description
response string The response from the reachable service

Sample response

HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "firstname": "Test", "lastname": "Person", "street_address1": "Street 1", "city": "Oslo", "zip_code": "0123", "ssn": "11223344556", "reachable": true, "identifier": "1234567890" }
Copy

Objects

This section describes all response objects within the REST API.

Campaign

Representation of a campaign that will be posted.

Object

BODY
Parameter Type Description
id Guid The campaign object's unique id.
name String A friendly name to identify the campaign.
output_date Date Date in UTC format representing the date when you would like your envelope printed & distributed.
cost_center String Value representing an internal cost center.
envelope_count Int Value representing the total number of envelopes in the campaign.
state String State type denominator, see the section State values for valid values..
state_changed_at Date Date in UTC format representing the date when the campaign state was changed.
created_at Date Date in UTC format representing the date when the campaign was created.
{ "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" }
Copy

State values

VALUES
String Description
opened The campaign is opened, you can add envelope, modify or change state to cancelled.
closed The campaign is marked as ready for production and can not be modified.
transferred The campaign and all linked envelopes has been transferred to our production facility.
completed The campaign and all linked envelopes has been printed and posted.
cancelled The campaign has been closed and all linked envelopes will not be printed or distributed.
failed The campaign could not be produced in our facility, contact our customer service for further details.

Envelope

Representation of an envelope that will be posted.

Object

BODY
Parameter Type Description
id Guid The envelope object's unique id.
name String A friendly name to identify the envelope.
address Object Address object that represents the destination, see the section Address objects for valid formats.
Remark: In the case of a postal address, the address needs to be embedded into the uploaded document. The one exception to an embedded address is when the flag 'use_coverpage' is lit on the postal address object. A 'null' value will be treated as an address of type postal.
postage String Postage type denominator, see the section Postage values for valid values.
Remark: For customers registered to our Norwegian production site, this parameter can be considered redundant as it is ignored
plex String Plex type denominator, see the section Plex values for valid values.
color Boolean Print the content in color (CMYK), if set to false the content will be printed in black and white.
state String State type denominator, see the section State values for valid values.
pu Boolean Personal delivery, additional service for REK
consignor_contact String Email for integration with the PostNord-app and receipt mail, additional service for REK
state_changed_at Date Date in UTC format representing the date when the envelope state was changed.
created_at Date Date in UTC format representing the date when the envelope was created.
transaction Object Transaction object that the state of the Envelop Transaction object.

Sample request

{ "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" } }
Copy

Postage values

VALUES
Value Description
priority Your content will be delivered within one working day after it's been printed and posted.
economy Your content will be delivered within four working days after it's been printed and posted.
rek Mailings that needs to be signed by the recipient before hand out.
protected Mailings to recipients who have protected identities.

Plex values

VALUES
Parameter Description
simplex We will only print on the front of each paper sheet.
duplex We will print on both the front and back of each paper sheet.

State values

VALUES
Parameter Description
opened The envelope is in opened state, you can add content, modify or cancel the envelope.
closed The envelope is in closed state, it's marked as ready for print & distribution.
transferred The envelope has been transferred to our production facility, and can no longer be modified or cancelled.
printed The envelope has been printed in our production facility.
posted The envelope has been posted.
cancelled The envelope has been cancelled, and will not be printed or distributed.
failed The envelope could not be produced in our facility, contact our customer service for further information.

Address

Object (postal)

The envelopes content will be printed and will be sent with regual postal mail. Note: The address is still required to be embedded inside the document unless the use_coverpage flag is used.

In case of Registered mail/REK, certain limitations apply to the different address rows. name and street have a max limit of 35 characters/row and postal_code a limit to five digits only (with or without blankspaces).

BODY
Parameter Type Description
$type String Denominator for the address type, should always be set to 'postal'.
Remark: this parameter must come first in the json object.
name String[] The recipient's name, each string in the array is considered to be a address line.
street String[] The recipient's street name, each string in the array is considered to be a address line.
postal_code String The recipient's postal/zip code.
city String The recipient's city name.
country String The recipient's country name or country code as a ISO 3166-1 encoded alpha-2 code. See an official list of country codes.
use_coverpage Boolean On true: A flyleaf page will be added to the envelope containing the address details.
{ "$type": "postal", "name": [ "Company Inc.", "c/o John Doe" ], "street": [ "Street no. 37" ], "postal_code": "65421", "city": "Gothenburg", "country": "SE", "use_coverpage": true }
Copy

Object (email)

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

BODY
Parameter Type Description
$type String Denominator for the address type, should always be set to 'email'.
Remark: this parameter must come first in the json object.
subject String The value will be set as the email's subject field.
subject String The recipient's email adress, to where the contents of the envelope will be sent.
{ "$type": "email", "subject": "Invoice 9923891", "recipient": "johndoe@johndoe.com" }
Copy

Object (einbox_kivra)

Type 'invoice.renewal' will soon be supported by Kivra.

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

BODY
Parameter Type Description
$type String Denominator for the address type, should always be set to 'einbox_kivra'.
Remark: this parameter must come first in the json object.
recipient String The recipient of the einbox's social security number, to where the contents of the envelope will be sent.
subject String The value will be displayed as subject in the recipient's e-inbox if supported.
Remarks: if a template has been specified this value will be ignored and the stored subject of the template will be used instead.
sender_id String Optional to set other sender then the default.
kivra_type Int 0: Letter (Default), 1: Invoice, 2: Letter Salary, 3: Booking, 4: Invoice Renewal
booking Object
Parameter Type Description
title String Title for the booking
start_time Date The bookings start time
end_time Date (Optional) The bookings end time
location String (Optional) Location address
description String (Optional) Description
info_url String (Optional) Url
invoice Object
Parameter Type Description
reference String Tenants own reference
payable Boolean If should be payable
currency String Currency used in specifying total_owed. Ex. SEK, DKK, NOK
due_date Date Date when this Invoice is due
total_owed String (float) The total amount owed according to the invoice. If payable equals true this must be a non negative number that's greater than "0"
use_ocr Boolean True: OCR, False: reference
use_bg Boolean True: BG, False: PG
account String Tenant's account number
payment_reference String The reference number used for paying. This can be maximum 25 characters long
variable_amount Boolean Toggles whether the user may choose to pay only a portion of the total_owed amount or whether the user must always pay the complete total_owed amount
min_amount String (float) The minimum amount that can be paid when variable_amount equals true. Note that this is a soft limit, so whenever variable_amount is true the user will be able to choose freely the amount to be paid, but it may be warned if the amount paid is inferior to min_amount. min_amount must be greater than "0" and less than "total_owed".
{ "$type": "einbox_kivra", "subject": "Bokning 1543", "recipient": "19590422XXXX", "kivra_type": 3, "booking": { "title": "Välkommen på årets besök", "start_time": "2021-03-06 15:00", "end_time": "2021-03-06 17:30", "description": "Beskrivning av händelse", "location": "Drottningtorget 5, 411 03 Göteborg", "info_url": "https://www.ekopost.se" } }
Copy

{ "$type": "einbox_kivra", "subject": "faktura 02102", "recipient": "19830706XXXX", "kivra_type": 1, "invoice": { "reference": "01253679", "payable": true, "currency": "SEK", "due_date": "2021-06-28", "total_owed": "123.75", "use_ocr": false, "use_bg": true, "account": "0000-0000", "payment_reference": "1234023" } }
Copy

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. Used for Digipost (Norway) and MinaMeddelanden (Sweden).

BODY
Parameter Type Description
$type String Denominator for the address type, should always be set to 'einbox'.
Remark: this parameter must come first in the json object.
recipient String The recipient of the einbox's social security number, to where the contents of the envelope will be sent.
template String The id of a predefinied ekopost template. The stored subject and content of the template will be used instead of any subject/content specified in the request.
subject String The value will be displayed as subject in the recipient's e-inbox if supported.
Remarks: if a template has been specified this value will be ignored and the stored subject of the template will be used instead.
content String The specified content will be displayed as html/text message in the recipients e-inbox if supported.
Remarks: if a template has been specified this value will be ignored and the stored content of the template will be used instead.
sender_id String Optional to set other sender then the default.
{ "$type": "einbox", "subject": "Invoice 9923891", "recipient": "19800101xxxx" }
Copy

Object (einbox_signer)

The content will be sent to a digital inbox (einbox) ,if it exist, owned by the recipient and also to a given email, if the einbox doesn't exist the document can be signed by bank-id login.

BODY
Parameter Type Description
$type String Denominator for the address type, should always be set to 'einbox_signer'.
Remark: this parameter must come first in the json object.
info_mail String Email inbox that should receive information and the covenant document when all parties has signed the document.
sender_id String Optional to set other sender then the default.
signers Object[] Signer object that represents the signers
signers.email String Email address where the link for singing the document will be sent
signers.recipient String The recipient's social security number.
signers.issuer Boolean The issuer of the signing document
Remark: Can be true for one signer.
{ "$type": "einbox_signer", "info_mail": "infoepost@företaget1.com", "signers": [ { "email": "johndoe1@johndoe1.com", "recipient": "19800101xxxx", "issuer": true, }, { "email": "johndoe2@johndoe2.com", "recipient": "19800202xxxx", "issuer": false, } ] }
Copy

Object (einvoice)

The envelopes content will be transfered electronically to the recipient.

BODY
Parameter Type Description
$type String Denominator for the address type, should always be set to 'einvoice'.
Remark: this parameter must come first in the json object.
format String Format type denominator, see the section Format values for valid values.
sender String Identifier of the sender, this is usually the sender's registration number.
sender_type String Identifier type denominator, see the section Identifier type values for valid values.
recipient String Identifier of the recipient, this is usually the recipient's registration number.
recipient_type String Identifier type denominator, see the section Identifier type values for valid values.
intermediator String Intermediator type denominator, see the section Intermediator values for valid values.
Remark: If the recipient is using Ekopost to receive eletronic documents or the intermediator is not found or unkwon, set the value to 'null'.
{ "$type": "einvoice", "format": "svefaktura-1.0", "sender": "556838-4118", "sender_type": "SE.REGNO", "recipient": "556838-4118", "recipient_type": "SE.REGNO", "intermediator": null }
Copy

Format values

VALUES
Value Description
svefaktura-1.0 This represents version 1.0 of svefaktura.
svefaktura-2.0-invoice This represents version 2.0 of svefaktura, type invoice.
svefaktura-2.0-creditnote This represents version 2.0 of svefaktura, type creditnote.
peppol-bis-billing-3.0 This represents version 3.0 of peppol delivery.

Identifier values

VALUES
Value Description
SE.REGNO This represents a swedish company registration number, format e.g. "556838-4118".
SE.SSNNO This represents a swedish personal social security number, format e.g. "YYMMDD-XXXX".
GS1.GLN This represents a global location number (GLN) based on the GS1 general specifications.

Intermediator values

VALUES
Value Description
peppol Pan-European Public Procurement Online.

Object (Navet lookup)

Ekopost need information about your Navet-connection before this can be used.

Returns postal address-object that will be transformed and used as address for current envelope.

BODY
Parameter Type Description
$type String Denominator for the address type, should always be set to 'lookup'.
Remark: this parameter must come first in the json object.
recipient String Social security number
{ "$type": "lookup", "recipient": "18750710XXXX" }
Copy

Object (ebank)

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

BODY
Parameter Type Description
$type String Denominator for the address type, should always be set to 'ebank'.
Remark: this parameter must come first in the json object.
recipient String An identifier (FMI) of the recipient, the identifier is usually provided by the bank or through a lookup service.
customer_number String External identifier of the customer, this is usually a number stored in the senders system.
customer_name String Name of the customer.
invoice_number String The external invoice number.
reference_type String The external reference type used as a reference when paying the invoice, type can be either 'ocr' or 'message'.
reference_value String The external reference value used as a reference when paying the invoice.
giro_number String The giro account number of the payment recipient.
Remark: This value should not contain dashes, only numbers.
autogiro Boolean Set to true if the invoice is payed through autogiro.
Remark: Setting this to true will disable manual payment of the invoice in the internet bank.
amount String The total amount of the invoice.
invoice_date String Date when the invoice was issued.
due_date String Date when the invoice payment is due.
issuer String Optional to send from this issuer instead of default issuer.
presentation_reference String Optional to set presentation reference.
{ "$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": "55683841", "autogiro": true, "amount": 499.99, "invoice_date": "2015-01-01T00:00:00", "due_date": "2015-01-31T00:00:00" }
Copy

Object (protected)

The envelope's content will be sent as a letter to the specified.

BODY
Parameter Type Description
$type String Denominator for the address type, should always be set to 'protected'.
Remark: this parameter must come first in the json object.
recipient String The recipient's' SSN (personnummer) or other identifier.
use_coverpage Boolean On true: A flyleaf page will be added to the envelope containing the address details.
{ "$type": "protected", "recipient": "yyyyMMdd-xxxx", "use_coverpage": true }
Copy

Object (mastercard)

The envelope's content will be sent as an invoice

BODY
Parameter Type Description
$type String Denominator for the address type, should always be set to 'einvoice_mastercard'.
Remark: this parameter must come first in the json object.
sender_id String Your customer's id number/string
kid String The KID of the invoice.
credit_account String The credit account of the invoice.
issuer String The issuer of the invoice.
shipment_id Guid The shipment id of the invoice.
account_number String The account number of the invoice.
amount Double The amount of the invoice.
due_date String (DateTime) The due date of the invoice.
payment_type String The payment type of the invoice. One of:
EFAKTURA,
EFAKTURA_AND_AVTALEGIRO,
EFAKTURA_AND_EXTERNAL_AVTALEGIRO,
AVTALEGIRO
document_type int The document type of the invoice. One of:
0 = INVOICE,
1 = CREDIT_NOTE,
2 = REMINDER,
3 = COLLECTION_NOTICE,
4 = DUNNING,
5 = PAYMENT_REQUEST,
6 = ENFORCEMENT_WARNING
efaktura_identifier String The efaktura identifier of the invoice.
social_security_number String The social security_number of the invoice.
e_faktura_reference String The efaktura reference of the invoice.
minimum_amount Double (nullable) The minimum amount of the invoice.
brand_name String (nullable) The brand name of the invoice. Must be set when sending EFAKTURA, EFAKTURA_AND_AVTALEGIRO, EFAKTURA_AND_EXTERNAL_AVTALEGIRO
e_faktura_url String (nullable) The external url of the invoice.
collection_notice_notification_email String (nullable) The external url of the invoice.
collection_notice_notification_mobile_phone String (nullable) The external url of the invoice.
atg_notification Bool The external url of the invoice.
atg_notification_text String (nullable) The atg notification text of the invoice.
atg_abbreviated_name String (nullable) The atg abbreviated name of the invoice.
atg_external_reference String (nullable) The atg external reference of the invoice.
{ "$type": "einvoice_mastercard", "sender_id": "12345", "kid": "", "credit_account": "11223344556", "issuer": "987654321", "shipment_id": "4357b0f9-2d83-4782-ab24-aa590c7027f7", "account_number": "22113344665", "amount": 100.00, "due_date": "2024-01-01", "payment_type": "EFAKTURA", // only one of the three following should be set, depending on if you send efaktura, avtalsgiro etc. "efaktura_identifier": "789456123", // use the reachable api to get the efaktura identifier if you don't already have it. "social_security_number": null, "e_faktura_reference": null, "minimum_amount": null, "brand_name": null, "e_faktura_url": null, "collection_notice_notification_email":null, "collection_notice_notification_mobile_phone": null, // atg "atg_notification": false, "atg_notification_text": null, "atg_abbreviated_name": null, "atg_external_reference": null" } or shorter version for EFAKTURA: { "$type": "einvoice_mastercard", "sender_id": "12345", "kid": "", "credit_account": "11223344556", "issuer": "987654321", "account_number": "22113344665", "amount": 100.00, "due_date": "2024-01-01", "payment_type": "EFAKTURA", // only one of the three following should be set, depending on if you send efaktura, avtalsgiro etc. "efaktura_identifier": "789456123", "minimum_amount": null }
Copy

Transaction

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

Object

BODY
Parameter Type Description
state String State type denominator, see the section State values for valid values.
state_changed_at Date Date in UTC format representing the date when the campaign state was changed.
"transaction" : { "state" : "completed", "state_changed_at" : "2015-01-01T12:00:00" }
Copy

Content

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

Object

BODY
Parameter Type Description
id Guid The content object's unique id.
mime String The original file's mime type.
length Int The original file's size in bytes.
type String Content type denominator, see the Type values section for valid values.
created_at Date Date in UTC format representing the date when the content was created.
{ "id": 100, "mime": "application/pdf", "length": 1024, "type": "document", "created_at": "2015-01-01T12:00:00" }
Copy

Type values

VALUES
Value Description
document The object intance represents the main document.
attachment The object intance represents an attachment.
markup The object intance represents a xml markup.

Error

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

Object

BODY
Parameter Type Description
error_code String Code that represents the error that occured.
error_message String Description about what error occured.
developer_message String Further description about the error for developers.
{ "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." }
Copy

Error code values

VALUES
Value Description
0Invalid basic authentication token.
100AThe envelope must contain atleast one (1) document before being closed.
100BThe envelope must contain atleast one (1) markup before being closed.
101A campaign must contain atleast one (1) envelope before being closed.
102All envelopes inside a campaign must be closed before closing the campaign.
103An envelope may only contain one (1) document.
104An envelope may only contain content with mime of 'application/pdf'.
105Could not extract or identify a postal address in the envelopes main documents.
106Campaign was not found.
107Could not open the main document content or find any pages.
108An envelope may only contain content of type 'attachment' with mime set to 'application/pdf'.
109An envelope may only contain content of type 'markup' with mime set to 'application/xml'.
110An envelope may only contain one (1) markup.
111Envelope was not found.
112Specified country is not a valid ISO 3166-1 encoded alpha-2 code.
113You have exceeded your credit limit for the month, please contact our customer service to adjust your credit limit.
114The searchparams is null.
115The searchparams is invalid.
116The timespan is invalid.
117The document size is invalid.
118The attachment size is invalid.
119Missing recipient.
120Missing email
121Can not create more envelopes in campaign
122One signer needed
123Email address contains invalid characters.
124FUI-number is not registrered
125No applicants registrered for this FUI
126Not unique
127Invalid data
128Wrong mime for sms. Mime should be 'text/plain'
129Empty data field
130Sms text message not encoded into base64
131Sms recipients contains invalid phone number.
132Sms does not contain any recipients
133Sms "FromName" is null or empty.
134Sms too many recipients (100 000 is the max limit)
135Address validation error, error contains more details such as "Name too long (max 35 characters)"
136Invalid contract, error contains more details.
137Document content not found on the specified envelope
138Recipient can not be the same as the issuer
139Recipient must have a valid valuer
140No setup for protected mailing, contact hejsan@ekopost.se to get started with protected mailing.
141Invalid contract
142Reply mail template missing
143More than 50 documents over 8Mb sent current day

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
Copy

Usage

Using the Ekopost nuget package Table of contents 5 step walkthrough the minimum required steps needed to schedule an envelope initialize create a new campaign create a new Envelope create a new Content close the campaign and envelope cancel and review objects creating an Ebank Address object 5 step walkthrough Initialization Setting up the Ekopost class to target your account. In order to integrate with Ekopost you must first provide an API key that is linked to your account, this key can be found in the portal https://secure.ekopost.se. Once you have your key you can use it as a parameter to instantiate an Ekopost object as seen in [CODE EXAMPLE 1] below [CODE EXAMPLE 1] -initialize - - - - - - - - - - - - - - - - - - - - - using Ekopost.Contracts; . . . 1 var eko = new Ekopost.Ekopost("apikeystring"); . . . - - - - - - - - - - - - - - - - - - - - - Now when we have an Ekopost object, [eko], there are 3 important functions to note: eko.CampaignSet.Create(); eko.EnvelopeSet.Create(Guid campaignId); eko.ContentSet.Create(Guid campaignId, Guid envelopeId); In this tutorial we will go through each of the objects created by these functions with example of how to use them and in the process we will have scheduled our first mail for delivery using the Ekopost nuget package. Content can be thought of as the letter that you wish to send. That letter needs to be put in an envelope and a campaign can contain multiple envelopes. When we code this using the nuget package we do it in reverse and create the campaign first, then the envelope and finally the content. Lets get started with the campaign Campaign [CODE EXAMPLE 2] -create a new campaign - - - - - - - - - - - - - - - - - - - - - . . . 1 var newCampaign = new Campaign("myFirstCampaign","", DateTime.Now.AddHours(2)); 2 3 var campaignSet = eko.CampaignSet.Create(); 4 5 var registeredCampaign = campaignSet 6 .Create(newCampaign) 7 .Resource; . . . - - - - - - - - - - - - - - - - - - - - - first we create a campaign object on line 1. In the example it has been given a name [myFirstCampaign], providing a blank cost center and schedules the send outs to two hours from now. Next we use the first function mentioned above to create a CampaignSet object, this is what we use when we want to manipulate campaigns. Note that no interaction with Ekopost has yet occurred, on the line 6 however an API call is made by calling the Create() function campaignSet. This function return a wrapper object with metadata on the API call, the Resource property contains the registered campaign. We are interested in the returned campaign object because it contains an Id that needs to be referenced in our next step. Envelope [CODE EXAMPLE 3] -create a new Envelope - - - - - - - - - - - - - - - - - - - - - . . . 1 var postalAddress = new AddressPostal( 2 new[] { "Johnny Doh" }, 3 new[] { "Ekovägen 12" }, 4 "43215", 5 "Ekostaden", 6 "SE"); 7 var envelope = new Envelope("firstLetter", postalAddress, Postage.Economy, Plex.Simplex, false); 8 var envelopeSet = eko.EnvelopeSet.Create(registeredCampaign.Id); 9 var registeredEnvelope = envelopeSet 10 .Create(envelope) 11 .Resource; . . . - - - - - - - - - - - - - - - - - - - - - an envelope needs a destination, so we start by making an address object on line 1-6. There are multiple address types however this tutorial covers only a postal address type. Now when we have an address we can use it as a parameter when creating an envelope as is seen on line 7. Once again we create a Set item (line 8), this time the EnvelopeSet, so that we can manipulate envelopes in Ekopost, note that we need to use the Id of the campaign item [registeredCampaign] we received in [CODE EXAMPLE 2]. Just like before we make an API call and register our envelope with Ekopost via the Create() method on line 9-11. Content [CODE EXAMPLE 4] -create a new Content - - - - - - - - - - - - - - - - - - - - - . . . 1 var content = new Content(ContentType.Document, "~path/to/file/on/disk/aletter.pdf"); 2 var contentSet = eko.ContentSet.Create(registeredCampaign.Id, registeredEnvelope.Id); 3 contentSet.Create(content); . . . - - - - - - - - - - - - - - - - - - - - - this is where we upload our letter, what we call content. It is required that an envelope contains a document type Content, this is the main content of any envelope, so on line 1 we create such content. In this example we point to the file that we want to upload from disk by using a path parameter. Next, line 2, we use our last Set item, namely that of a ContentSet, to manage our content, this time we need to supply the campaign [registeredCampaign] id from [CODE EXAMPLE 2] and also the envelope [registeredEnvelope] Id from [CODE EXAMPLE 3]. Finally on line 3 we make the API call. OK all set? Not quite! More envelopes and more content can be created as desired, once done we need to mark the campaign and the envelope as ready for delivery Close [CODE EXAMPLE 5] -close the campaign and envelope - - - - - - - - - - - - - - - - - - - - - . . . 1 envelopeSet.Close(registeredEnvelope.Id); 2 campaignSet.Close(registeredCampaign.Id); . . . - - - - - - - - - - - - - - - - - - - - - by using our Set objects we call the close function on both envelopes and campaigns, this will mark them as ready for our system to send them on to their destination. Note that once they are closed you may no longer modify them, you may however cancel, provided you do it before the scheduled send out time. Cancel and Review [CODE EXAMPLE 6] - cancel and review objects - - - - - - - - - - - - - - - - - - - - - . . . 1 envelopeSet.Cancel(registeredEnvelope.Id); 2 campaignSet.Cancel(registeredCampaign.Id); 3 envelopeSet.List().Resource; 4 campaignSet.List().Resource; . . . - - - - - - - - - - - - - - - - - - - - - Line 1 and 2 shows how to cancel envelopes and campaigns respectively line 3 and 4 shows how to retrieve a collection of envelopes and campaigns respectively. The List() function also accepts parameters to filter the returned result. envelopeSet has string name and string state as filter parameters and campaignSet has DateTime? start, DateTime? stop, string name and string state. Using the Ebank Address object When sending an invoice directly to a customers bank account, the Ebank address should be used. this object (ebankAddress) will replace the postalAddress object from [CODE EXAMPLE 3] when creating an Envelope. [CODE EXAMPLE 7] - Creating an Ebank Address object - - - - - - - - - - - - - - - - - - - - - . . . 1 var ebankAddress = new AddressEbank( 2 "5568384118.BNK.SE", 3 "556838-4118", 4 "No Ink AB", 5 "556838", 6 ReferenceTypes.Ocr, 7 "0000556838411800", 8 "5568-3841", 9 false, 10 499.99M, 11 Convert.ToDateTime("2019-09-17T00:00:00"), 12 Convert.ToDateTime("2019-09-20T00:00:00")); . . . - - - - - - - - - - - - - - - - - - - - - The parameters used when creating an Ebank address are further described in the Object (ebank) section above
Copy

Sandbox

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. Create a sandbox user. Click here to create.

2. If you already have created a sandbox-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.

Webhooks

Set up Webhooks to receive status when campaign is completed.

You can access webhook-setup in secure API-settings menu here.

Webhooks allow you to build or set up integrations which subscribe to certain Ekopost events. When one of those events is triggered, we'll send a HTTP POST payload to the webhook's configured URL. Once installed, the webhook will be triggered each time one or more subscribed events occurs.

Event

Webhooks are only subscribed to the campaign completed event for now. For example, if you subscribe to webhooks event you'll receive a payload every time a campaign is completed and statuses for all envelopes in the campaign.

Payloads

You'll get a specific payload with the envelopes id and status information.

Delivery header

HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain one special header:

X-Ekopost-Signature The HMAC hex digest of the response body. The HMAC hex digest is generated using the sha1 hash function and the secret as the HMAC key.

Example delivery

POST /payload HTTPS/1.1 Host: localhost:4567 X-Ekopost-Signature: 7d38cdd689735b008b3c702edd92eea23791c5f6 Content-Type: application/json [ { "ObjectId": "5b161d7a-8a62-44ca-94c2-a2d9d2819be3", "StatusName": "posted" }, { "ObjectId": "9916aa7a-442a-8a62-94c2-a2d672819b99", "StatusName": "posted" } ]
Copy

Code examples

Overview

In these examples we're using Newtonsoft.Json and Newtonsoft.Json.Linq along with RestSharp.

Variables used:

_apiKey see documentation

_host is either sandbox or production -base url

Get method used in the examples

private IRestResponse Get(string url) { var client = new RestClient(); var request = new RestRequest($"{_host}{url}"); request.Method = Method.GET; request.AddHeader("Authorization", $"api-key {_apiKey}"); request.AddHeader("Content-Type", "application/json; charset=UTF-8"); return client.Get(request); }
Copy

Post method used in the examples

private IRestResponse Post(string url, string requestBody = null) { var client = new RestClient(); var request = new RestRequest($"{_host}{url}").AddJsonBody(requestBody); request.Method = Method.POST; request.AddHeader("Authorization", $"api-key {_apiKey}"); request.AddHeader("Content-Type", "application/json; charset=UTF-8"); return client.Post(request); }
Copy

Sms

var body = new { // Required From = "Test", // Sender name or phone number Recipient = "+46701010101", // Recipient phone number Text = "Test text", // Sms text content Title = "Dispatch title", // Description of the sms // Optional Cost_Center = "Tester", // Cost center Unique_Id = "ref-22345-3", // Unique id to prevent duplicates WebhookUrl = "https://webhooks.codeexamples.abc/sms" // Where to receive status webhook }; var result = Post("dispatch/sms/", JsonConvert.SerializeObject(body, Formatting.None)); /* ToDo: Check result status */ dynamic response = JsonConvert.DeserializeObject(result.Content); /* ToDo: Check response status */ // Poll sms by Id var pollByIdResult = Get($"dispatch/sms/{response.id.ToString()}"); // Poll sms by UniqueId var pollByUniqueResult = Get($"dispatch/sms/unique/{response.unique_id.ToString()}");
Copy

Sample Response (RAW)

{ "from": "Test", "recipient": "+46701010101", "text": "VGVzdCB0ZXh0", "delivery_status": "Sending", "id": "793b8222-6565-45a7-940d-21897a5c433f", "type": "SMS", "state": "Transferred", "channel": "api", "created": "2024-02-07T11:40:00.6999378Z", "title": "Dispatch title", "cost_center": "Tester", "unique_id": "ref-22345-3" }
Copy

Sample Poll Response (RAW)

{ "from": "Test", "recipient": "+46701010101", "text": "VGVzdCB0ZXh0", "delivery_status": "Delivered", "delivery_status_message": "", "id": "793b8222-6565-45a7-940d-21897a5c433f", "type": "SMS", "state": "Completed", "channel": "api", "created": "2024-02-07T11:40:00Z", "title": "Dispatch title", "cost_center": "Tester", "unique_id": "ref-22345-3" }
Copy

Reply mail

Reply mail makes use of a "replymail-template" which the recipient folds into an envelope and returns it to the address printed on the template

Link to template

We will add an envelope to the mailing during production.

This feature needs to be set up per customer, contact hejsan@ekopost.se for more information.

Create reply mail

Reply mail are created the same way as regular postal mailings with these exceptions

1. Campaign body should have "replymail" set to "true"

// Create campaign var campaignBody = new { name = "Replymail example", output_date = DateTime.Now, cost_center = "", replymail = true // 1. }; var createCampaignResult = Post($"/campaigns/", JsonConvert.SerializeObject(campaignBody, Formatting.None)); var createCampaignObject = JsonConvert.DeserializeAnonymousType(createCampaignResult.Content, new { id = "" });
Copy

2. A replymail-template should be added as an attachment marked replymail

// Attach the reply mail template bytes = File.ReadAllBytes(@"File\Mall för svarsbrev för Svarspost ver 2.pdf"); fileBase64 = Convert.ToBase64String(bytes); var attachmentBody = new { data = fileBase64, mime = "application/pdf", length = 1024, type = "replymail", // 2. }; createContentResult = Post($"campaigns/{createCampaignObject.id}/envelopes/{createEnvelopeObject.id}/content", JsonConvert.SerializeObject(attachmentBody, Formatting.None)); createContentObject = JsonConvert.DeserializeAnonymousType(createContentResult.Content, new { id = "" });
Copy

Protected mailing

This feature needs to be set up per customer, contact hejsan@ekopost.se for more information.

Create protected mailing

Protected mailings are created the same way as regular postal mailings with these exceptions

1. Body of create envelope request should have postage = "protected"

2. and an address object of type "protected"

3. which should have a recipient in the form of ssn/pnr

// Create envelope var envelopeBody = new { name = "A protected letter", postage = "protected", // 1 plex = "simplex", color = false, address = new JObject { { "$type", "protected" }, // 2 { "recipient", "998811-XXXX" }, // 3 { "use_coverpage", false} } }; var createEnvelopeResult = Post($"campaigns/{createCampaignObject.id}/envelopes", JsonConvert.SerializeObject(envelopeBody, Formatting.None)); var createEnvelopeObject = JsonConvert.DeserializeAnonymousType(createEnvelopeResult.Content, new { id = "" });
Copy

If use_coverpage is set to false, the only thing that should be visible inside the address area is the recipients ssn/pnr.