> For the complete documentation index, see [llms.txt](https://docs.vomevolunteer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vomevolunteer.com/resources/opportunities/write-operations/create-opportunities.md).

# Create opportunities

This endpoint creates one or more opportunities inside a category.

<mark style="color:red;">Every opportunity needs a</mark> <mark style="color:red;">**category\_id**</mark><mark style="color:red;">, a</mark> <mark style="color:red;">**title**</mark><mark style="color:red;">, and at least one</mark> <mark style="color:red;">**coordinator**</mark><mark style="color:red;">. An opportunity with nobody responsible has no contact for the people who join it, which is why the coordinator is not optional.</mark>

#### Endpoint

```plaintext
POST api/opportunities/bulk-create/
```

#### Example Request Payload

```json
{
    "allow_partial": false,
    "opportunities": [
        {
            "category_id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
            "title": "Weekend Mentor",
            "description": "Support volunteers during weekend sessions.",
            "coordinator_ids": ["8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f"],
            "watcher_ids": ["1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"],
            "visibility": 0,       // 0 Public, 1 Private, 2 Semi Private
            "commitment_type": 0,  // 0 One time, 1 Recurring
            "location_type": 0,    // 0 On-site, 1 Remote
            "address": "7 Freedom Trail, Medway, Norfolk, MA, USA",
            "tags": [
                { "type": "vome", "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f" },
                { "type": "custom", "id": "9c0d1e2f-3a4b-5c6d-7e8f-9a0b1c2d3e4f" }
            ],
            "site_links": [
                { "site_id": "2b5b2f4e-9a1e-4a3f-9d21-0f0a2f5c77aa", "permission": "read" }
            ],
            "published": true
        }
    ]
}
```

#### Fields

| Field                 | Required | Description                                                    |
| --------------------- | -------- | -------------------------------------------------------------- |
| `category_id`         | yes      | The category this opportunity belongs to.                      |
| `title`               | yes      | The opportunity name.                                          |
| `coordinator_ids`     | yes      | At least one admin. The primary contact for people who join.   |
| `description`         | no       | Shown on the opportunity.                                      |
| `watcher_ids`         | no       | Admins kept informed behind the scenes.                        |
| `visibility`          | no       | `0` Public, `1` Private, `2` Semi Private. Defaults to Public. |
| `commitment_type`     | no       | `0` One time, `1` Recurring.                                   |
| `location_type`       | no       | `0` On-site, `1` Remote.                                       |
| `address`             | no       | Only for on-site opportunities.                                |
| `tags`                | no       | See **Tags** below.                                            |
| `is_tags_required`    | no       | Whether a user must match the tags to join.                    |
| `site_links`          | no       | Sites to link the opportunity to.                              |
| `chat_disabled`       | no       | Turns the opportunity chat off.                                |
| `shift_chat_disabled` | no       | Turns chat off for this opportunity's shifts.                  |
| `published`           | no       | `true` publishes it. Leave it out to create a draft.           |

#### Coordinators and watchers

Both take **admin** IDs, which are user IDs from [Admins](https://docs.vomevolunteer.com/resources/admins.md). A user who is not an admin of your organization is refused rather than quietly accepted, so a volunteer cannot end up as a coordinator by mistake.

#### Tags

Tags come from two lists, and a reference says which one it is:

```json
{ "type": "vome", "id": "..." }    // Vome's shared tag list
{ "type": "custom", "id": "..." }  // your organization's own tags
```

Both kinds can be mixed in one `tags` array. The two lists have independent IDs that can collide, which is why the type is required. List them with Opportunity Tags.

#### Visibility

<mark style="color:red;">The order is not alphabetical:</mark> <mark style="color:red;">**0 Public, 1 Private, 2 Semi Private**</mark><mark style="color:red;">. Check the opportunity after creating it if visibility matters to you.</mark>

#### Location

`location_type` `0` means on-site and accepts an `address`. `location_type` `1` means remote, and sending an address with it is rejected rather than ignored.
