# How To Circulate with Draft API using Specific URL

Source: https://docs.arcxp.com/en/products/publishing-platform/how-to-circulate-with-draft-api-using-specific-url.html

The purpose of this guide is to demonstrate how to circulate a document to a provided URL in lieu of automatic generation.

- Manually setting a circulation URL
- Requirements
- Existing document
- Circulating to a provided URL

## Requirements

- You are familiar with the basic usage of the API (HTTP, Authentication, etc).
- If you have not used the API before, or need a refresher, refer to [the Draft API documentation](https://dev.arcxp.com/api/content-administration/draft-api-sandbox/) and [Getting Started with the Draft API](https://dev.arcxp.com/publishing-platform/developer-docs/draft-api/getting-started-with-the-draft-api/).

## Existing document

Given two circulated documents, `URWCJIIJPNGEZKZR3EZ54TO22Y` and `67B2A6C51AEE442B95F8C921FF`, start by listing the active circulations for each.

```
curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/URWCJIIJPNGEZKZR3EZ54TO22Y/circulation

# RESPONSE
{
  "circulations": [
    {
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "website_id": "cyclist-daily",
      "website_url": "/wheels-news/2019/09/04/parade/",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/wheels-news",
          "website": "cyclist-daily"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/wheels-news",
            "website": "cyclist-daily"
          }
        }
      ]
    },
    {
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/parade/",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/news",
          "website": "river-city-post"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/news",
            "website": "river-city-post"
          }
        },
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/the-city",
            "website": "river-city-post"
          }
        }
      ]
    }
  ]
}
curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation

# RESPONSE
{
  "circulations": [
    {
      "document_id": "67B2A6C51AEE442B95F8C921FF",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/man-bites-dog/",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/news",
          "website": "river-city-post"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/news",
            "website": "river-city-post"
          }
        }
      ]
    }
  ]
}
```

These calls provide the following information:

- The document `URWCJIIJ...` is circulated on websites `cyclist-daily` and `river-city-post` at URLs `/wheels-news/2019/09/04/parade/` and `/news/2019/09/04/parade/` respectively.
- The document `67B2A6C5...` is circulated on website `river-city-post` at URL `/news/2019/09/04/man-bites-dog/`.

## Circulating to a provided URL

To circulate a document at a specific URL and skip automatic URL generation, provide a `website_url` value with the circulate call. `website_url` must be an unused URL or occupied by a redirect targeting the same document.

For instance, attempting to circulate `67B2A6C5...` to website `cyclist-daily` under the circulation URL for `URWCJIIJ...` fails.

```
curl --request PUT \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'content-type: application/json' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation/cyclist-daily \
  --data '{
    "website_url": "/wheels-news/2019/09/04/parade/"
  }'

# ERROR RESPONSE
{
    "error_code": "ErrUrlAlreadyExists",
    "error_message": "url /wheels-news/2019/09/04/parade/ already exists for website cyclist-daily"
}
```

Instead, circulating `67B2A6C5...` to the unused URL `/wheels-news/man-bites-dog` on `cyclist-daily` succeeds.

```
curl --request PUT \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'content-type: application/json' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation/cyclist-daily \
  --data '{
    "website_url": "/wheels-news/man-bites-dog/"
  }'

# SUCCESS RESPONSE
{
    "document_id": "67B2A6C51AEE442B95F8C921FF",
    "website_id": "cyclist-daily",
    "website_url": "/wheels-news/man-bites-dog/"
}
```

Listing the documents’ circulations again shows the updated websites and URLs.

```
curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/URWCJIIJPNGEZKZR3EZ54TO22Y/circulation

# RESPONSE
{
  "circulations": [
    {
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "website_id": "cyclist-daily",
      "website_url": "/wheels-news/2019/09/04/parade/",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/wheels-news",
          "website": "cyclist-daily"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/wheels-news",
            "website": "cyclist-daily"
          }
        }
      ]
    },
    {
      "document_id": "URWCJIIJPNGEZKZR3EZ54TO22Y",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/parade/",
      "website_primary_section": {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/news",
          "website": "river-city-post"
        }
      },
      "website_sections": [
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/news",
            "website": "river-city-post"
          }
        },
        {
          "type": "reference",
          "referent": {
            "type": "section",
            "id": "/the-city",
            "website": "river-city-post"
          }
        }
      ]
    }
  ]
}
curl --request GET \
  --header 'Authorization: Bearer <TOKEN>' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/67B2A6C51AEE442B95F8C921FF/circulation

# RESPONSE
{
  "circulations": [
    {
      "document_id": "67B2A6C51AEE442B95F8C921FF",
      "website_id": "cyclist-daily",
      "website_url": "/wheels-news/man-bites-dog/"
    },
    {
      "document_id": "67B2A6C51AEE442B95F8C921FF",
      "website_id": "river-city-post",
      "website_url": "/news/2019/09/04/man-bites-dog/"
    }
  ]
}
```

| **Note:** Don’t forget the trailing slash on all urls. |
| ------------------------------------------------------ |