DoveRunner Distributor Watermarking API Guide

This document guides how to use DoveRunner Distributor Watermarking Service through HTTP API.

Common Specifications

The specifications below are common to all Distributor Watermarking APIs described in this document.

Authentication Token

When calling the Distributor Watermarking API, you need to set an authentication token issued by the process below.

Step 1: Generate the base64 encoded Authorization parameter

1. Navigate to Base64 Enc/Dec page on DoveRunner DevConsole.
2. While Encrypt option is selected, enter the AccountID:AccessKey value in the left text field.
3. Base64 encoded output will be displayed as the screenshot below.
4. Copy the output value to use in the next step.

You need to input the AccountID and AccessKey values for your DoveRunner service account.

Step 2: Use the parameter value to generate the Authorization token.

Call the token API URL with base64 encoded value in the Authorization request header.

• URL: https://dwm.pallycon.com/api/token/{siteId}
• Method: GET

Path Parameter

Parameter	Type	Description
siteId	four alphanumeric characters	Your DoveRunner Site ID shown on Console

Request Header

Name	Description
Authorization	Basic Auth : Basic base64encode(accountId:accessKey)

Sample Request

GET /api/token/UNIT HTTP/1.1
Authorization: basic authInfo
Host: dwm.pallycon.com

Response Data Fields

Field	Type	Info
error_code	String	error code
error_message	String	error message
data.token	String	API Auth token

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 112

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "data" : {
    "token" : "Bearer valid-token"
  }
}

API Request Header

You can call the Distributor Watermarking API by setting the data issued through the token api in the authorization header.

Common Response Specifications

Response Status

HTTP Status Code	Description
Error code	Description
401	Incorrect JWT Token specification or user information not found
403	You do not have permission to use the API.
200	Success

Response Data Fields

Key	type	Value
error_code	String	0000: Success / Other values indicate failure
error_message	String	Error message
data	Json	Api result

Status Code

Job Status Code

Code	Description
DM000	READY
DM001	PREPROCESSING
DM500	COMPLETED
DM600	ERROR

Task Status Code

Code	Description
TK000	READY
TK001	PROGRESSING
TK002	COMPLETE
TK005	FAIL

Job API

Search Job List

Use this API to search the Job List.

• URL: https://dwm.pallycon.com/api/job/{siteId}
• Method: GET

Path Parameter

Parameter	Description
siteId	Your DoveRunner Site ID shown on Console

Request Parameters

Parameter	Type	Description
content_id	String	Enter the unique ID (Content ID) to be watermarked. (Special characters cannot be used, maximum 200 bytes)
job_status	Array	Search job status by list.
from	String	Search parameter for job registration time. (yyyy-MM-dd)
to	String	Search parameter for job registration time. (yyyy-MM-dd)
page_unit	Number	Number of max result per page. default : 25, max: 1000.
page_index	Number	Index of result page. default : 1
time_zone	String	Search timezone. (+/-hh:mm) default: +00:00

Sample Request

GET /api/job/UNIT?content_id=test&job_status=DM500&job_status=DM600&from=2023-11-07&to=2023-11-09&page_unit=10&page_index=1&time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: dwm.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	Error code
error_message	String	Error message
time_zone	String	Timezone
total_count	Number	Total Count
data	Array	Job list
data.[].job_id	Number	Job ID
data.[].content_id	String	Job name
data.[].job_status	String	Job status code
data.[].reg_time	String	Start time for the job
data.[].update_time	String	Last update time for the job

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 292

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "total_count" : 1,
  "data" : [ {
    "job_id" : 1111,
    "content_id" : "content_id",
    "job_status" : "DM000",
    "reg_time" : "2022-10-27T15:33:47",
    "update_time" : "2022-10-27T15:34:05"
  } ]
}

Get Job Detail

Use this API to Get the Job details.

• URL: https://dwm.pallycon.com/api/job/{siteId}/{jobId}
• Method: GET

Path Parameter

Parameter	Description
siteId	Your DoveRunner Site ID shown on Console
jobId	Job ID

Request Parameters

Parameter	Type	Description
time_zone	String	Search timezone. (+/-hh:mm) default: +00:00

Sample Request

GET /api/job/UNIT/727?time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: dwm.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	Error code
error_message	String	Error message
time_zone	String	Timezone
data	Object	Job Detail
data.job_id	Number	Job ID
data.content_id	String	Job name
data.job_status	String	Job status code
data.reg_time	String	Start time for the job
data.update_time	String	Last update time for the job

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 266

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : {
    "job_id" : 727,
    "content_id" : "content_id",
    "job_status" : "DM500",
    "reg_time" : "2022-09-13T18:46:28",
    "update_time" : "2022-09-13T18:56:02"
  }
}

Get All Recipients Of a Job

Use this API to get all related Recipients of a job.

• URL: https://dwm.pallycon.com/api/job/{siteId}/{jobId}/recipient
• Method: GET

Path Parameter

Parameter	Description
siteId	Your DoveRunner Site ID shown on Console
jobId	Job ID

Request Parameters

Parameter	Type	Description
time_zone	String	Search timezone. (+/-hh:mm) default: +00:00

Sample Request

GET /api/job/UNIT/727/recipient?time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: dwm.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	Error code
error_message	String	Error message
time_zone	String	Timezone
total_count	Number	total count
data	Array	Recipient List
data.[].dwm_id	Number	Recipient id
data.[].recipient	String	Recipient Name
data.[].description	String	Recipient Description
data.[].task_status	String	PreEmbedder Task Status
data.[].cli_error_code	String	PreEmbedder Error Code (“0” : Success, else are fail.)
data.[].reg_time	String	Start time for the job
data.[].update_time	String	Last update time for the job

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 285

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "total_count" : 1,
  "data" : [ {
    "dwm_id" : 74,
    "recipient" : "test1",
    "description" : "description",
    "task_status" : "TK001",
    "cli_error_code" : "0",
    "reg_time" : "2022-04-05T14:35:39",
    "update_time" : "2022-04-05T17:35:39"
  } ]
}

Recipient

The recipient name must be unique and can only contain English letters (uppercase and lowercase), decimal numbers, hyphens (-), underscores (_), and periods (.). No other special characters such as @, #, $, % etc supported. However, the system treats recipient names in a case-insensitive manner. This means that if you register Test, you cannot register variations like TEST or test as separate recipient names. Similarly, when using a DWM ID, regardless of the case used in the request (e.g., test), the system will utilize the DWM ID associated with the originally registered recipient name (e.g., Test).

Search Recipient List

Use this API to search recipients.

• URL: https://dwm.pallycon.com/api/recipient/{siteId}
• Method: GET

Path Parameter

Parameter	Description
siteId	Your DoveRunner Site ID shown on Console

Request Parameters

Parameter	Type	Description
search_keyword	Array	Search recipient’s name
from	String	Search parameter for job registration time. (yyyy-MM-dd)
to	String	Search parameter for job registration time. (yyyy-MM-dd)
page_unit	Number	Number of max result per page. default : 25, max: 1000.
page_index	Number	Index of result page. default : 1
time_zone	String	Search timezone. (+/-hh:mm) default: +00:00

Sample Request

GET /api/recipient/UNIT?search_keyword=test&from=2023-11-07&to=2023-11-09&page_unit=10&page_index=1&time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: dwm.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	Error code
error_message	String	Error message
time_zone	String	Timezone
total_count	Number	Total Count
data	Array	Recipient List
data.[].dwm_id	Number	Recipient id
data.[].name	String	Recipient Name
data.[].description	String	Recipient Description
data.[].reg_time	String	Start time for the recipient

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 235

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "total_count" : 1,
  "data" : [ {
    "dwm_id" : 9,
    "name" : "distributor_1",
    "description" : "8337",
    "reg_time" : "2023-01-12T13:30:30"
  } ]
}

Get Recipient Detail

Use this API to Get Recipient Info in Detail.

• URL: https://dwm.pallycon.com/api/recipient/{siteId}/{dwmId}
• Method: GET

Path Parameter

Parameter	Description
siteId	Your DoveRunner Site ID shown on Console
dwmId	Recipient’s DWM ID

Request Parameters

Parameter	Type	Description
time_zone	String	Search timezone. (+/-hh:mm) default: +00:00

Sample Request

GET /api/recipient/UNIT/1011?time_zone=%2B00%3A00 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Host: dwm.pallycon.com

Response Data Fields

Field	Type	Description
error_code	String	Error code
error_message	String	Error message
time_zone	String	Timezone
data	Array	Recipient List
data.dwm_id	Number	Recipient id
data.name	String	Recipient Name
data.description	String	Recipient Description
data.reg_time	String	Start time for the recipient
data.update_time	String	Last update time for the recipient

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 235

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : {
      "dwm_id" : 1011,
      "name" : "distributor_1",
      "description" : "8337",
      "reg_time" : "2023-01-12T13:30:30",
      "update_time" : "2023-07-22T03:39:11"
  }
}

Register Recipient

Use this API to register recipient. You can add maximum 150 recipients/users at a time. But if you try to add more than that, registration will fail.

• URL: https://dwm.pallycon.com/api/recipient/{siteId}
• Method: POST

Path Parameter

Parameter	Description
siteId	Your DoveRunner Site ID shown on Console

Request Data Fields

Field	Type	Required	Description
recipients	Array	Y	List of Recipient
recipients.[].name	String	Y	Name (maximum 128 length) Allow only Alphabet, Number, (-_.)
recipients.[].description	String		Description (maximum 50 length)

Sample Request

POST /api/recipient/UNIT HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Content-Length: 86
Host: dwm.pallycon.com

{
  "recipients" : [ {
    "name" : "test",
    "description" : "test corp."
  } ]
}

Response Data Fields

Field	Type	Description
error_code	String	Error code
error_message	String	Error message
time_zone	String	Timezone
data	Array	Recipient List
data.[].dwm_id	Number	Recipient id
data.[].name	String	Recipient Name
data.[].description	String	Recipient Description
data.[].reg_time	String	Start time for the job

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 220

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : [ {
    "dwm_id" : 10,
    "name" : "test",
    "description" : "test corp.",
    "reg_time" : "2023-01-12T13:30:30"
  } ]
}

Modify Recipient

Use this API to modify recipient. Only available when the recipient is not used on DWM pre-embedding process.

• URL: https://dwm.pallycon.com/api/recipient/{siteId}/{dwmId}
• Method: PUT

Path Parameter

Parameter	Description
siteId	Your DoveRunner Site ID shown on Console
dwmId	Recipient’s DWM ID

Request Data Fields

At least name or description field will be submitted.

Field	Type	Required	Description
name	String		Name (maximum 128 length)
description	String		Description (maximum 50 length)

Sample Request

PUT /api/recipient/UNIT/1011 HTTP/1.1
Authorization: Bearer valid_token
Content-Type: application/json;charset=UTF-8
Content-Length: 86
Host: dwm.pallycon.com

{
    "name" : "change_name",
    "description" : "change_name corp."
}

Response Data Fields

Field	Type	Description
error_code	String	Error code
error_message	String	Error message
time_zone	String	Timezone
data	Object	Recipient List
data.dwm_id	Number	Recipient id
data.update_time	String	Last update time for the job

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 220

{
  "error_code" : "0000",
  "error_message" : "Success.",
  "time_zone" : "+00:00",
  "data" : {
    "dwm_id" : 1011,
    "update_time" : "2023-07-22T03:39:11"
  }
}