Code App API

1. Introduction

The Code Application holds imported codes and when it is integrated with the Business Messenger app, it delivers a number of codes on demand. The codes in the Code App are sorted in the lists, which are defined group of codes.

When the Code app is integrated, the codes can be used, for example as a part of a message that will be sent in a campaign.

The Code app integration is done with OAuth2 protocol for the app authentication.

The subject domain of an endpoint URL is:

https://api{separator}{platform_domain}/code/v1

Note: A domain is presented with placeholders as https://api{separator}{platform_domain}, where {separator} can be a dot (.) or a hyphen (-). Please, replace it with your actual platform domain name.

2. Integration with the Business Messenger App

The Code app has to be registered as a client application for App Access in the Security application first. The Client Credentials that are given while registration, has to be filled in the Settings > Code Integration section, in order to integrate the Code app with the Business Messenger app.

For the integration the following details are needed:

• OAuth Client ID - OAuth Client ID of the Code app.
• OAuth Client Secret - OAuth Client Secret of the Code app.
• After the OAuth Client ID and Client Secret are added, the Code app accounts can be obtained by clicking the 'Obtain Code app accounts' button.
• Code Account - a code account can be selected from the drop-down list.

2.1 Sending Codes in a Campaign

When the Code App is integrated, the list of codes can be used in a campaign.

While creating a campaign, the option 'Insert a Code List' will be available just in case the Code App is integrated into the Business Messenger App.
After selecting this option, a Code List can be selected from the drop-down list. By clicking on the 'Insert Code List' button, a code list will be connected with the campaign.

The code app will deliver codes at the moment of sending the campaign. How many codes will be delivered, depends on how many contacts are included in the campaign, and also how many codes are available in the selected list of codes. In case that there are not enough codes in the list for all campaign messages, the campaign will send just a number of messages with codes.

3. Methods Overview

With the following endpoints Code data can be managed and published.

3.1 Accounts

Endpoints to list and manage the Code App accounts.

3.2 Lists

Endpoints to list and manage code lists.

3.3 Codes

Endpoints for listing and managing codes.

4. Methods Details

4.1 Accounts

Endpoints to list and manage the Code App accounts.

Method Overview

The method returns a list of the Code app accounts.

Parameters

Name	Type	Description
name	string (query)	Search for a name.
q	string (query)	General search criteria.
sort	string (query)	Sort order for the result records. Available values: name, -name.
status	string (query)	Filter by account status. Available values: active, inactive. Default value: active.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.

Responses

Code	Description	Links
200	Account collection.	No links
default	Unexpected Error.	No links

Success Response 200: Account Collection

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Method Overview

The method returns an Account data.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1.

Responses

Code	Description	Links
200	Account data.	No links
default	Unexpected Error.	No links

Success Response 200: Account Data

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

4.2 Lists

Endpoints to list and manage code lists.

Method Overview

The method returns an array of code lists.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1.
name	string (query)	Search for a name.
q	string (query)	General search criteria.
sort	string (query)	Sort order for the result records. Available values: name, -name, totalCodesActive, -totalCodesActive, totalCodesPublished, -totalCodesPublished, totalPublications, -totalPublications, createdDt, -createdDt, canPublishFrom, -canPublishFrom, canPublishUntil, -canPublishUntil.
status	string (query)	Filter by list status. Available values: active, inactive, draft. Default value: active.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.

Responses

Code	Description	Links
200	Array of code lists.	No links
default	Unexpected Error.	No links

Success Response 200: Array of Code Lists

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Method Overview

The method creates a new list.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1.
body (required)	object (body)	Post data. List to add.

Post Data Parameters

{
  "name": "string",
  "status": "active",
  "codesUnique": "yes",
  "publicationOrder": "sequential",
  "canPublishFrom": "2024-08-14T14:41:09.566Z",
  "canPublishUntil": "2024-08-14T14:41:09.566Z",
  "maxPublications": 0
}

Responses

Code	Description	Links
201	New list response.	No links
default	Unexpected Error.	No links

Success Response 201: New List Response

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Method Overview

The method returns a list by a list UUID.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1.
listUuid (required)	string (path)	ID of a list to get.

Responses

Code	Description	Links
200	List data.	No links
default	Unexpected Error.	No links

Success Response 200: List of Data

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Method Overview

The method updates a list.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1.
listUuid (required)	string (path)	UUID of a list to update.
body (required)	object (body)	List data. See below an example.

Example object for a list:

{
  "name": "string",
  "status": "active",
  "codesUnique": "yes",
  "publicationOrder": "sequential",
  "canPublishFrom": "2024-08-14T14:55:53.657Z",
  "canPublishUntil": "2024-08-14T14:55:53.657Z",
  "maxPublications": 0
}

Responses

Code	Description	Links
200	Resource updated.	No links.
400	Invalid request.	No links.
404	Resource not found.	No links.
405	Validation exception.	No links.
default	Unexpected error.	No links.

Success Response 200: Resource Updated

Error Response 400: Invalid Request

Error Response 404: Resource Not Found

Error Response 405: Validation Exception

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Method Overview

The method deletes a list.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1
listUUid (required)	string (path)	UUID of a List to be deleted.

Responses

Code	Description	Links
204	List deleted successfully.	No links
default	Unexpected Error.	No links

Success Response 200: List Deleted Successfully

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

4.3 Codes

Endpoints for listing and managing codes.

Method Overview

The method returns a list of codes from a list.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1.
listUuid (required)	string (path)	List UUID. Default value: 70826a10-3f7f-11eb-9690-bb2d1f43df7c.
code	string (query)	Search for a code.
q	string (query)	General search criteria.
sort	string (query)	Sort order for the result records. Available values: code, -code, sortNum, -sortNum.
status	string (query)	Filter by code status. Available values: active, inactive, published, redeemed. Default value: active.
page_number	integer (query)	Page number. Default value is 1.
page_size	integer (query)	Page size. Default value is 10.

Responses

Code	Description	Links
200	List of codes.	No links
default	Unexpected Error.	No links

Success Response 200: List of Codes

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Method Overview

The method creates a new code.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1.
listUuid (required)	string (path)	List UUID. Default value: 70826a10-3f7f-11eb-9690-bb2d1f43df7c.
body (required)	object (body)	Post data. Code to add.

Post Data Parameters

{
  "code": "string",
  "sortNum": 0
}

Responses

Code	Description	Links
201	New code response.	No links
default	Unexpected Error.	No links

Success Response 201: New Code Response

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Method Overview

The method returns a code.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1.
listUuid (required)	string (path)	List UUID. Default value: 70826a10-3f7f-11eb-9690-bb2d1f43df7c.
codeId (required)	integer (path)	ID of a code to get.

Responses

Code	Description	Links
200	Code data.	No links
default	Unexpected Error.	No links

Success Response 200: Code Data

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Method Overview

The method deletes a code.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1
listUUid (required)	string (path)	List UUID. Default value: 70826a10-3f7f-11eb-9690-bb2d1f43df7c.
codeId (required)	integer (path)	ID of a code to delete.

Responses

Code	Description	Links
204	Code deleted successfully.	No links
default	Unexpected Error.	No links

Success Response 204: Code Deleted Successfully

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Method Overview

The method imports new codes.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1.
listUuid (required)	string (path)	List UUID. Default value : 70826a10-3f7f-11eb-9690-bb2d1f43df7c
body (required)	object (body)	Post data. Codes to import.

Post Data Parameters

[
  {
    "code": "string",
    "sortNum": 0
  }
]

Responses

Code	Description	Links
201	Import response.	No links
default	Unexpected Error.	No links

Success Response 201: Import Response

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

Method Overview

The method publishes existing codes. To publish codes means to assign existing codes to receivers.

Parameters

Name	Type	Description
accountUuid (required)	string (path)	Account UUID. Default value: c7e5fd78-3ebf-11eb-80a5-0755a3865fd1.
listUuid (required)	string (path)	List UUID. Default value : 70826a10-3f7f-11eb-9690-bb2d1f43df7c
body (required)	array (body)	Post data. Receivers that will be provided with the published codes.

Post Data Parameters

[
  {
    "receiverId": "string"
  }
]

Responses

Code	Description	Links
201	Publish response.	No links
default	Unexpected Error.	No links

Success Response 201: Publish Response

An example of publish response:

[
  {
    "receiverId": "receiver1",
    "code": "123"
  },
  {
    "receiverId": "receiver2",
    "code": "124"
  }
]

Error Response Unexpected Error: Default

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

5. Data Models

Data Models define the structure of a JSON document and describe the data related to the Code App API.

5.1 AccountCollection

AccountCollection object properties:

Name	Type	Description
data (required)	array	An array of AccountResponse objects.
meta (required)	object	CollectionMeta object.

5.2 AccountResponse

AccountResponse object properties:

Name	Type	Description
uuid	string	Account UUID.
name	string	Account name.
status	string	Status of an account. Possible values: active, inactive, deleted.
createdDt	string($date-time)	Account creation date and time.
updatedDt	string($date-time)	Account updated date and time.

5.3 ListCollection

ListCollection object properties:

Name	Type	Description
data (required)	array	An array of List objects.
meta (required)	object	CollectionMeta object.

5.4 List

List object properties:

Name	Type	Description
uuid	string	List UUID.
name	string	List name.
status	string	Status of a list. Possible values: active, inactive, deleted, draft.
codesUnique	string	If codes are unique. Possible values: yes, no.
publicationOrder	string	Codes order. Possible values: sequential, random.
canPublishFrom	string($date-time)	Date and time when a list can be published.
canPublishUntil	string($date-time)	Date and time until a list can be published.
createdDt	string($date-time)	List creation date and time.
updatedDt	string($date-time)	Date and time when a list is updated.
maxPublications	integer	Max number of publications.
totalCodesActive	integer	Total number of active codes.
totalCodesPublished	integer	Total number of published codes.
totalPublications	integer	Total number of publications.

5.5 ListCreate

ListCreate object properties:

Name	Type	Description
name (required)	string	List name.
status (required)	string	Status of a list. Possible values: active, draft.
codesUnique (required)	string	If codes are unique. Possible values: yes, no.
publicationOrder (required)	string	Codes order. Possible values: sequential, random.
canPublishFrom (required)	string($date-time)	Date and time when a list can be published.
canPublishUntil (required)	string($date-time)	Date and time until a list can be published.
maxPublications	integer	Max number of publications.

5.6 ListUpdate

ListUpdate object properties:

Name	Type	Description
name (required)	string	List name.
status (required)	string	Status of a list. Possible values: active, inactive, draft.
codesUnique (required)	string	Possible values: yes, no.
publicationOrder (required)	string	Codes order. Possible values: sequential, random.
canPublishFrom (required)	string($date-time)	Date and time when a list can be published.
canPublishUntil (required)	string($date-time)	Date and time until a list can be published.
maxPublications	integer	Max number of publications.

5.7 CodesCollection

CodesCollection object properties:

Name	Type	Description
data (required)	array	An array of Code objects.
meta (required)	object	CollectionMeta object.

5.8 Code

Code object properties:

Name	Type	Description
id	integer	Code ID.
code	string	Code.
status	string	Status of a code. Possible values: active, inactive, deleted, published, redeemed.
createdDt	string($date-time)	Code date and time of creation.
updatedDt	string($date-time)	Date and time when a code is updated.
publishedDt	string($date-time)	Date and time when a code is published.
deletedDt	string($date-time)	Date and time of a code deletion.
deactivatedDt	string($date-time)	Date and time of a code deactivation.
sortNum	integer	Sorting number of a code.
receiverId	string	Receiver ID.

5.9 CodeCreate

CodeCreate object properties:

Name	Type	Description
code (required)	string	Code.
sortNum	integer	Sorting number of a code.

5.10 ImportRequest

ImportRequest object properties:

Name	Type	Description
data	array	An array of ImportItem objects.

5.11 ImportItem

ImportItem object properties:

Name	Type	Description
code (required)	string	Code.
sortNum	integer	Sorting number of a code.

JSON Example

[
  {
    "code": "string",
    "sortNum": 0
  }
]

5.12 ImportResponse

ImportResponse object properties:

Name	Type	Description
invalid	integer	If code is invalid.
imported	integer	If code is imported.

5.13 PublishRequest

PublishRequest object properties:

Name	Type	Description
data	array	An array of PublishRequestItem objects.

5.14 PublishRequestItem

PublishRequestItem object properties:

Name	Type	Description
receiverId	string	Receiver ID.

JSON Example

[
  {
    "receiverId": "string"
  }
]

5.15 PublishResponse

PublishResponse object properties:

Name	Type	Description
data	array	An array of PublishResponseItem objects.

5.16 PublishResponseItem

PublishResponseItem object properties:

Name	Type	Description
code	string	Code.
receiverId	string	Receiver ID.

5.17 Error

Error object properties:

Name	Type	Description
code (required)	string	Error code.
message (required)	string	Error message.
description	string	Description.
items	array	An array of ErrorItem objects.

5.18 ErrorItem

ErrorItem object properties:

Name	Type	Description
name (required)	string	Error item name.
message (required)	string	Error item message.
description	string	Description.

JSON Example

{
  "code": "string",
  "message": "string",
  "description": "string",
  "items": [
    {
      "name": "string",
      "message": "string",
      "description": "string"
    }
  ]
}

5.19 CollectionMeta

CollectionMeta object properties:

Name	Type	Description
pagination	object	CollectionMetaPagination object.

5.20 CollectionMetaPagination

CollectionMetaPagination object properties:

Name	Type	Description
total (required)	integer	Total number of rows.
count (required)	integer	Number of rows in the current page.
perPage (required)	integer	The maximum rows per page.
currentPage (required)	integer	The current page number.
totalPages (required)	integer	Total number of pages.
links (required)	object	CollectionMetaPaginationLinks object.

5.21 CollectionMetaPaginationLinks

CollectionMetaPaginationLinks object properties:

Name	Type	Description
first	string	Link to the first page.
last	string	Link to the last page.
prev	string	Link to the previous page.
next	string	Link to the next page.

JSON Example

"meta": {
    "pagination": {
      "total": 0,
      "count": 0,
      "perPage": 0,
      "currentPage": 0,
      "totalPages": 0,
      "links": {
        "first": "string",
        "last": "string",
        "prev": "string",
        "next": "string"
      }
    }
  }