# How to Bulk Circulate Documents in Draft API

Source: https://docs.arcxp.com/en/products/publishing-platform/how-to-bulk-circulate-documents-in-draft-api.html

The purpose of this guide is to demonstrate how to circulate a document to many websites at once.

## Goals

At the end of this guide, a user will be able to circulate and decirculate a document to and from many websites with one API call using the`/bulk-circulation`endpoint.

## Prerequisites

If you haven’t already done so, read [Getting Started with the Draft API](https://dev.arcxp.com/publishing-platform/developer-docs/draft-api/getting-started-with-the-draft-api/).

This guide assumes that:

- You have already created a document.
- The document is not circulated to any websites.
- You want to circulate the document to many websites at once.
- You are familiar with the basic usage of the API (HTTP, Auth, etc).

## Existing Uncirculated Document

For the purpose of this guide, let’s assume our Document already exists with a Document ID of `EHVJEKSMRFAMXE2BRWO2QN6XLU`.

Let’s take a look at the Document:

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

# RESPONSE
{
    "id": "EHVJEKSMRFAMXE2BRWO2QN6XLU",
    "type": "STORY",
    "draft_revision_id": "44AN46CQSZE2LDRMJSINK3O3JI"
}
```

And its current circulations:

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

# RESPONSE
{
  "circulations": []
}
```

We can see that:

- The document is created, but not yet published
- The document has no circulations

## Adding Circulations

Luckily, Draft API supports a `/bulk-circulation` endpoint, so that I can mass circulate with an API call.

Let’s say I want to circulate my document:

- On website `river-city-post` to section `/news`
- On website `cyclist-daily` to section `/local`
- I want `river-city-post/news` to be the primary website and section

```
curl --request PUT \
  --header 'Authorization: Bearer ' \
  --header 'Content-Type: application/json' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/circulation/bulk-circulation \
  --data '[
  {
    "document_id": "EHVJEKSMRFAMXE2BRWO2QN6XLU",
    "website_id": "river-city-post",
    "website_url": "/news/interesting-thing-happens",
    "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"
        }
      }
    ]
  },
  {
    "document_id": "EHVJEKSMRFAMXE2BRWO2QN6XLU",
    "website_id": "cyclist-daily",
    "website_url": "/local/interesting-thing-at-local-place",
    "website_primary_section": {
      "type": "reference",
      "referent": {
        "type": "section",
        "id": "/local",
        "website": "cyclist-daily"
      }
    },
    "website_sections": [
      {
        "type": "reference",
        "referent": {
          "type": "section",
          "id": "/local",
          "website": "cyclist-daily"
        }
      }
    ]
  }
]'
```

You’ll notice that my circulation endpoint is not tied to a specific website, and I’m able to circulate to many websites by feeding in an array of circulation objects.

### Verifying the Circulations

Let’s verify that the document has been circulated to both websites by using the GET `/circulation` endpoint:

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

# RESPONSE
{
    "circulations": [
        {
            "document_id": "EHVJEKSMRFAMXE2BRWO2QN6XLU",
            "website_id": "cyclist-daily",
            "website_url": "/local/interesting-thing-at-local-place",
            "website_primary_section": {
                "type": "reference",
                "referent": {
                    "type": "section",
                    "id": "/local",
                    "website": "cyclist-daily"
                }
            },
            "website_sections": [
                {
                    "type": "reference",
                    "referent": {
                        "type": "section",
                        "id": "/local",
                        "website": "cyclist-daily"
                    }
                }
            ]
        },
        {
            "document_id": "EHVJEKSMRFAMXE2BRWO2QN6XLU",
            "website_id": "river-city-post",
            "website_url": "/news/interesting-thing-happens",
            "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"
                    }
                }
            ]
        }
    ]
}
```

Great. I’m circulated to both websites, and only needed to make one call.

## Decirculating From Many Websites

Uh oh. Turns out my document was not supposed to go to either of those websites. Quickly, let’s reverse those circulations.

```
curl --request DELETE \
  --header 'Authorization: Bearer ' \
  --url https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/bulk-circulation?website=river-city-post&website=cyclist-daily
```

Much like the singular decirculation endpoint, decirculating from a website removes the document from all sections on that website. By setting website query params for both websites, I can decirculate from all sections on multiple websites at once.

### Verifying the Decirculation

To quickly verify my delete call worked, I can use the `/circulation` endpoint:

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

# RESPONSE
{
  "circulations": []
}
```

And now my document is back to no circulations.

## Summing it up

In this short guide, you:

```
# Verified the document existed
GET https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU

# Listed all its circulations
GET https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/circulation

# Circulated the document to many websites at once
PUT https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/bulk-circulation { ... }

# Decirculated the document from many websites
DELETE https://api.{{org}}.arcpublishing.com/draft/v1/story/EHVJEKSMRFAMXE2BRWO2QN6XLU/bulk-circulation?website=cyclist-daily&website=river-city-post
```