---
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](/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. Navigate to [Base64 Enc/Dec page](https://devconsole.doverunner.com/common-tools/#base64) 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.

![](/img/content-security/tnp-token-auth-base64.png)

> 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                                                     | 
|------------------|-----------------------------------------------------------------|
| 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.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](/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"
  }
}
```