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.doverunner.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.doverunner.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
200	Success
400	Bad Request: The request was invalid. Common causes include duplicate recipient names (E4004) or a failed site key decryption/AES check (E1003).
401	Unauthorized: The authentication token is missing, malformed, or has expired .
402	Invalid Parameter: A required parameter is missing, or its value, format, or type is invalid .
403	Forbidden: You do not have the necessary permissions to access this API or Site ID .
405	Method Not Allowed: The HTTP method used is not supported for this endpoint .
422	Unprocessable Entity: The request is well-formed but cannot be followed. For example, the recipient limit per request or total plan quota was exceeded .
500	Internal Server Error: An unexpected error occurred on the server side while processing the request.
503	Service Unavailable: The authentication server or DWM service is temporarily unreachable or suspended.

Response Data Fields

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

Error Code

The error_code field is 0000 when the request succeeds. Any other value means the request failed, and error_message carries the detail. The tables below list the error codes that the Distributor Watermarking APIs described in this document can return.

Authentication Error Code

These errors are returned by the shared authentication layer, before the API itself runs. The Distributor Watermarking API accepts either a Bearer token in the Authorization header or a pallycon-apidata value, so both sets of codes are listed together.

Error Code	Description	Solution
E9000	The request did not carry a usable credential, or the endpoint does not accept the authentication method that was used.	Send Authorization: Bearer TOKEN, or send a pallycon-apidata value on endpoints that accept AES authentication.
E9001	The Authorization header is malformed or does not use the Bearer scheme.	Send the header exactly as Authorization: Bearer TOKEN.
E9002	The token was read but its payload failed verification, or a required claim is missing.	Reissue the token from DoveRunner Console and retry.
E9003	The token has expired.	Issue a new token and retry.
E9006	The account is not allowed to act on the requested Site ID, or the endpoint is restricted to administrator accounts.	Check the Site ID in the request path and call the API with an account that owns that site.
E9008	The account resolved from the token has no API token registered.	Check the account setup in DoveRunner Console, or contact the Helpdesk.
E9015	The pallycon-apidata payload was decrypted but the result is not valid JSON.	Make sure the JSON you encrypt into pallycon-apidata is well formed.
A1000	The pallycon-apidata value could not be decoded, or its encData or hash field is missing.	Rebuild the pallycon-apidata payload as described in the integration guide.
A1002	The timestamp in pallycon-apidata is missing, or is not in an accepted format.	Send the timestamp as yyyy-MM-ddTHH:mm:ssZ.
A1006	The Site Key or Access Key could not be decrypted, or encData could not be decrypted with the Site Key.	Confirm that the Site Key and Access Key match the values issued in DoveRunner Console.
A1007	The hash in pallycon-apidata does not match the value computed from the Access Key, Site ID, encData and timestamp.	Recompute the SHA-256 hash over your Access Key, Site ID, encData and timestamp, in that order.

API Error Code

Error Code	Description	Solution
E1000	A request parameter is missing, or its value, format or type is invalid. The error message names the field that failed.	Correct the field named in error_message and retry.
E1005	The Distributor Watermarking service is not active for this site.	Activate the service in DoveRunner Console, or contact the Helpdesk.
E2003	Failed to get the job list.	Retry, and contact the Helpdesk if the error persists.
E2004	Failed to get the job. The requested job ID may not exist for this Site ID.	Check the job ID in the request path and retry.
E2005	Failed to get the recipients of the job.	Check the job ID in the request path, retry, and contact the Helpdesk if the error persists.
E4000	Failed to get the recipient list.	Retry, and contact the Helpdesk if the error persists.
E4001	More than 150 recipients were sent in a single registration request.	Split the list into batches of 150 or fewer and call the API once per batch.
E4002	Failed to create the recipients.	Retry, and contact the Helpdesk if the error persists.
E4003	The number of recipients exceeds the amount available for your plan.	Contact the Helpdesk to raise your recipient allowance.
E4004	Every requested recipient name is already registered. Recipient names must be unique and are compared without regard to case.	Request only names that are not registered yet.
E4005	The number of recipients exceeds the trial limit of 10.	Upgrade to a commercial plan to register more recipients.
E4006	The recipient has already been used in a watermarking job, so it can no longer be modified.	Register a new recipient instead. A recipient name cannot be changed once it has been used.
E4007	Failed to update the recipient.	Retry, and contact the Helpdesk if the error persists.
E4008	The requested DWM ID does not belong to the requested Site ID.	Check the DWM ID and Site ID in the request path.
E4009	Failed to get the recipient.	Retry, and contact the Helpdesk if the error persists.
E4010	No recipient matches the requested DWM ID.	Check the DWM ID against the recipient list and retry.
E4017	Failed to allocate a DWM ID range while registering the first recipients for this site.	Retry, and contact the Helpdesk if the error persists.
E9997	An internal error occurred while processing the server response.	Retry, and contact the Helpdesk if the error persists.
E9998	The HTTP method is not supported on the requested URL.	Check the method and URL against this guide.
E9999	Internal error occurred.	Contact the Helpdesk with the time of the request.

E1000 is returned with HTTP status 402 Payment Required. Despite the name of that status, it always means that a request parameter is missing or invalid — it is never a billing or payment problem.

Status Code

Job Status Code

Code	Description
DM000	READY
DM100	PREPROCESSING
DM500	COMPLETED
DM600	ERROR

Task Status Code

Code	Description
TK000	READY
TK001	PROGRESSING
TK002	COMPLETE
TK003	STOP_REQUEST
TK004	STOPPED
TK005	FAIL

Job API

Search Job List

Use this API to search the Job List.

• URL: https://dwm.doverunner.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.doverunner.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.doverunner.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.doverunner.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.doverunner.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.doverunner.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.). Non-zero values correspond to the DWM PreEmbedder Error Code table (D0000–D0401, Axxxx).
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.doverunner.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.doverunner.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.doverunner.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.doverunner.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. If you need to register more than 150 recipients, split the list into multiple batches and call this API once per batch (≤150 recipients each).

• URL: https://dwm.doverunner.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.doverunner.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. Once a recipient’s name has been used in a DWM PreEmbedder job, it can no longer be renamed — decide on your naming convention before first use, since there is no rollback for a locked recipient.

• URL: https://dwm.doverunner.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.doverunner.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"
  }
}