Api documentation

Learn how to get started with our Api documentation

Documentation

API Reference - CorrespondenceAPI 1 Json Yaml Try

Correspondence API handles the automated generation of batches of pre-formatted correspondence, typically integrating customer/product specific data in correspondence templates for variable aspects of content. Channel applications can use this API to deliver alerts, reminders, advices, past due notices, announcements, campaign offers, statements and other arrangement reports. Correspondence API also offers rendering of documents in .pdf and .docx formats from predefined templates and supplied data. For self-service applications such as mobile or web, Correspondence API offers virtual mailbox for private exchange of messages between bank and customer. Last, but not least, customer notifications preferences are maintained so that notifications of interest to customer are delivered over preferred channels.

Working with communications

Schedule communication for delivery

POST /v1/correspondence/communications

Parameter Type/Format Description
cmd
required

Body /

The initiate delivery command.

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

201 - Communication initiated 

{}

Update delivery statuses of multiple communications

POST /v1/correspondence/communications/statuses

Parameter Type/Format Description
cmd
required

Body /

Update delivery statuses command

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

204 - No content - Communication status updated

Get the list of communications for delivery

GET /v1/correspondence/communications

Response contains list of communications that match filters.

Parameter Type/Format Description
contact-medium
required

Query / String

Contact medium designated for the delivery of the communication For a list of allowed values see [contact-medium](correspondence-classifications.html#contact-medium) enumeration.

page
optional

Query / Integer

Page index. For more information see general guidance on [paging and sorting]()

page-size
optional

Query / Integer

Number of items on a page. For more information see general guidance on [paging and sorting]()

sort-by
optional

Query / String

Attribute of the collection item to sort by. For more information see general guidance on [paging and sorting]().

sort-order
optional

Query / String

Sort order (`asc` or `desc`). Default is asc. For more information see general guidance on [paging and sorting]()

statuses
required

Query / Array

Delivery status of the communication.

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

200 - OK 

{
  "items": [
    {
      "communication-id": "string",
      "contact": {
        "usage": "string",
        "kind": "string",
        "details": "string",
        "contact-preference": {
          "preferred-language": "string",
          "opt-ins": [
            {}
          ],
          "opt-outs": [
            {}
          ],
          "uri": "string"
        },
        "uri": "string"
      },
      "customer-number": "string",
      "created": "string",
      "status": "string",
      "sent": "string",
      "expires": "string",
      "message-kind": "string",
      "priority": "string",
      "retry-count": "integer",
      "message": {
        "title": "string",
        "body": {
          "content-type": "string",
          "content": "string"
        },
        "attachments": [
          {
            "content-type": "string",
            "content": "string",
            "name": "string",
            "content-url": "string"
          }
        ]
      }
    }
  ]
}

Working with templates

Render formatted content based on template

POST /v1/correspondence/templates/render

Parameter Type/Format Description
cmd
required

Body /

Renders document.

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

200 - OK

Working with mailbox

Get mailbox messages for authenticated user

GET /v1/correspondence/me/messages

Parameter Type/Format Description
categories
optional

Query / Array

Categories that group similar messages. See [Message Category](correspondence-classifications.md#message-category) classification

from-time
optional

Query / String

Time of the first communication to be returned.

include
optional

Query / Array

List of fields to include in response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)

page
optional

Query / Integer

Page index. For more information see general guidance on [paging and sorting]()

page-size
optional

Query / Integer

Number of items on a page. For more information see general guidance on [paging and sorting]()

sort-by
optional

Query / String

Attribute of the collection item to sort by. For more information see general guidance on [paging and sorting]().

sort-order
optional

Query / String

Sort order (`asc` or `desc`). Default is asc. For more information see general guidance on [paging and sorting]()

statuses
required

Query / Array

Mailbox status of the communication

to-time
optional

Query / String

Date of last transaction. Default value is today.

trim
optional

Query / Array

List of fields to trim from response. For more information see general guidance on [response shaping](common-getstarted.html#shaping)

Response

200 - OK

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]() 

{
  "items": [
    {
      "message-id": "string",
      "customer-number": "string",
      "received": "string",
      "status": "string",
      "mailbox-folder": "string",
      "message-kind": "string",
      "urgency": "string",
      "message": {
        "title": "string",
        "body": {
          "content-type": "string",
          "content": "string"
        },
        "attachments": [
          {
            "content-type": "string",
            "content": "string",
            "name": "string",
            "content-url": "string"
          }
        ]
      },
      "message-category": "string",
      "has-attachments": "boolean",
      "is-read": "boolean"
    }
  ]
}

Get specific message

GET /v1/correspondence/me/messages/{message-id}

Parameter Type/Format Description
message-id
required

Path / String

The unique identifier of the mailbox message

Response

200 - OK

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]() 

{
  "message-id": "string",
  "customer-number": "string",
  "received": "string",
  "status": "string",
  "mailbox-folder": "string",
  "message-kind": "string",
  "urgency": "string",
  "message": {
    "title": "string",
    "body": {
      "content-type": "string",
      "content": "string"
    },
    "attachments": [
      {
        "content-type": "string",
        "content": "string",
        "name": "string",
        "content-url": "string"
      }
    ]
  },
  "message-category": "string",
  "has-attachments": "boolean",
  "is-read": "boolean"
}

Get mailbox summary for authenticated user

GET /v1/correspondence/me/messages/summary

Parameter Type/Format Description
statuses
required

Query / Array

Mailbox status of the communication

Response

200 - OK

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]() 

{
  "total-count": "integer",
  "items": [
    {
      "status": "string",
      "count": "integer"
    }
  ]
}

Mark message as read

POST /v1/correspondence/me/messages/{message-id}/mark-as-read

Parameter Type/Format Description
message-id
required

Path / String

The unique identifier of the mailbox message

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

204 - No content - Marked as read

Archive mailbox messages

POST /v1/correspondence/me/messages/archive

Parameter Type/Format Description
cmd
required

Body /

Archive messages command

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

204 - No content - Archived

Working with classifications

List all classification schemas used by the API

GET /v1/correspondence/classifications

Some fields and parameters have been restricted to a list of allowed lookup values maintained by the bank. This method lists all schemas used in this API.

Parameter Type/Format Description

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

200 - Success 

{
  "items": [
    {
      "schema-id": "string",
      "name": "string",
      "description": "string"
    }
  ]
}

List values allowed by given classification schema.

GET /v1/correspondence/classifications/{schema-id}

Returns all classification values for chosen classification.

Parameter Type/Format Description
schema-id
required

Path / String

Identifier of classification schema

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

200 - OK 

{
  "schema-id": "string",
  "name": "string",
  "description": "string",
  "values": [
    {
      "literal": "string",
      "code": "string",
      "description": "string",
      "parent-literal": "string"
    }
  ]
}

Working with notification preferences

Change notification preferences for authenticated user

POST /v1/correspondence/me/notification-preferences

Sets notification preference for user. Preference for certain notification may apply to specific account. Only changed preferences should be supplied within a command.

Parameter Type/Format Description
cmd
required

Body /

Set notification preferences command

Response

204 - No content - preferences set

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

List predefined notification groups

GET /v1/correspondence/notification-groups

Response contains list of predefined notification groups with default settings for channels, threshold and freequency

Parameter Type/Format Description

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

200 - OK 

{}

Get notification preferences for authenticated user

GET /v1/correspondence/me/notification-preferences

Response contains notifications preferences with thresholds and channel preferences

Parameter Type/Format Description

Response

default - Besides specific status codes above, other standard http [status codes](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html) can be returned for each request. To learn more see general guidance on [common-getstarted.html#error handling]()

200 - OK 

{}