> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/basic-scenarios/collection/collection-management-in-oz-api.md).

# Collection (1:N) Management in Oz API

This article describes how to create a collection via API, how to add persons and photos to this collection and how to delete them and the collection itself if you no longer need it. You can do the same in [Web console](/oz-knowledge/guides/user-guide/oz-webui/blacklist.md), but this article covers API methods only.

> Collection in Oz API is a database of facial photos that are used to compare with the face from the captured photo or video via the Collection analysis

> Person represents a human in the collection. You can upload several photos for a single person.

### How to Create a Collection

The collection should be created within a company, so you require your company's `company_id` as a prerequisite.

If you don't know your ID, call `GET /api/companies/?search_text=test`, replacing "test" with your company name or its part. Save the `company_id` you've received.

Now, create a collection via `POST /api/collections/`. In the request body, specify the alias for your collection and `company_id` of your company:

```json
{
  "alias": "your_collection",
  "company_id": "your_company_id"
}
```

In a response, you'll get your new collection identifier: `collection_id`. 

### How to Add a Person or a Photo to a Collection

To add a new person to your collection, call `POST /api/collections/{{collection_id}}/persons/`, using `collection_id` of the collection needed. In the request body, add a photo or several photos. Mark them with appropriate [tags](/oz-knowledge/guides/developer-guide/api/oz-api/media-tags.md#tags-for-photo-files) in the payload:

```json
{
    "media:tags": {
        "image1": [
            "photo_selfie",
            "orientation_portrait"
        ]
    }
}
```

The response will contain the `person_id` which stands for the person identifier within your collection.

If you want to add a name of the person, in the request payload, add it as metadata:

```json
    "person:meta_data": {
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }
    },
```

To add more photos of the same person, call `POST {{host}}/api/collections/{{collection_id}}/persons/{{person_id}}/images/` using the appropriate `person_id`.  The request body should be filled as you did it before with  `POST /api/collections/{{collection_id}}/persons/`.

To obtain information on all the persons within the single collection, call `GET /api/collections/{{collection_id}}/persons/`. 

To obtain a list of photos for a single person, call `GET /api/collections/{{collection_id}}/persons/{{person_id}}/images/`. For each photo, the response will contain`person_image_id`. You'll need this ID, for instance, if you want to delete the photo.

### How to Remove a Photo or a Person from a Collection

To delete a person with all their photos, call `DELETE /api/collections/{{collection_id}}/persons/{{person_id}}` with the appropriate collection and person identifiers. All the photos will be deleted automatically. However, you can't delete a person entity if it has any related analyses, which means the Collection analysis used this photo for comparison and found a match. To delete such a person, you'll need to delete these analyses using `DELETE /api/analyses/{{analysis_id}}` with `analysis_id` of the Collection (1:N) analysis.

To delete all the collection-related analyses, get a list of folders where the Collection analysis has been used: call `GET /api/folders/?analyse.type=COLLECTION`. For each folder from this list (`GET /api/folders/{{folder_id}}/`), find the `analysis_id` of the required analysis, and delete the analysis – `DELETE /api/analyses/{{analysis_id}}`.

To delete a single photo of a person, call `DELETE collections/<collection_id>/persons/<person_id>/images/<media_id>/` with collection, person, and image identifiers specified.

### How to Delete a Collection

Delete the information on all the persons from this collection as described above, then call `DELETE /api/collections/{{collection_id}}/` to delete the remaining collection data.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.ozforensics.com/oz-knowledge/guides/developer-guide/api/oz-api/basic-scenarios/collection/collection-management-in-oz-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.