--- title: "DoveRunner Distributor Watermarking API Guide" description: "This document guides how to use `DoveRunner Distributor Watermarking` Service through HTTP API." --- > For the complete documentation index, see [llms.txt](https://docs.doverunner.com/llms.txt). 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. Open the [Base64 encoder / decoder](https://lab.doverunner.com/playground/common-tools#base64) in the DoveRunner Lab Playground. 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** ```json 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** ```json 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** ```json 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](https://docs.doverunner.com/content-security/distributor-watermarking/distributor-watermarking-guide/#dwm-preembedder-error-code) (`D0000`–`D0401`, `Axxxx`). | | data.[].reg_time | String | Start time for the job | | data.[].update_time | String | Last update time for the job | **Sample Response** ```json 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** ```json 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** ```json 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** ```json 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** ```json 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" } } ```