# Purposes

A Purpose is *WHY* a company/organization processes a personal data.

Personal data a company/organization may process depends on **the legal reason for processing a personal** **data** and **the intended use**.

When a company obtains its clients’ personal data, it should explain in clear and plain language

* why it needs the data,
* how it will be using it,
* and how long it intends to keep it.

The processing should be tailored in a way that respects the key data protection principles.

* [Create a purpose](#create-a-purpose)
* [Fetch purposes](#fetch-purposes)
* [Update a purpose](#update-a-purpose)
* [Delete a purpose](#delete-a-purpose)

## Create a purpose

To create a new purpose, send a **POST** request on `/metadata/purposes` endpoint. You need to specify at least the purpose name (`description`) and a description (`details`).

```json
POST https://api.didomi.io/metadata/purposes?organization_id=YOUR_ORG_ID

{
  "description": "String",
  "details": "String",
  "reference": "String",
  "organization_id": "string",
  "namespaces": {
    "iab": "string",
    "iab2": "string",
    "didomi": "string",
    "custom": "string"
  },
  "metadata": {},
}
```

### Create a purpose with translations

Didomi supports translations (Check [here](https://developers.didomi.io/api-and-platform/introduction/translations) to see languages supported and their related code). To create a purpose with translations, you need to send a **POST** request on `/metadata/purposes` endpoint and add the query `$translations=true`. You need to specify the purpose name (`description`) and description (`details`) which become object with translation query param set to `true`.

```json
POST https://api.didomi.io/metadata/purposes
  ?$translations=true
  &organization_id=YOUR_ORG_ID

{
  "description": {
    "en": "",
    "fr": "",
    "it": ""
  },
  "details": {
    "en": "",
    "fr": "",
    "it": ""  
  }
}
```

## Fetch purposes

### Fetch all purposes

To retrieve all purposes from your Data Manager, you can send a **GET** request on `/metadata/purposes` endpoint.

```json
GET https://api.didomi.io/metadata/purposes?organization_id=YOUR_ORG_ID

{
  "total": 0,
  "limit": 0,
  "skip": 0,
  "data": [
    {
      "id": "string",
      "description": "String",
      "details": "String",
      "reference": "String",
      "organization_id": "string",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "metadata": {},
      "namespaces": {
        "iab": "string",
        "iab2": "string",
        "didomi": "string",
        "custom": "string"
      }
    }
  ]
}
```

### Fetch a purpose

To retrieve one purpose from your Data Manager, you can send a **GET** request on `/metadata/purposes/id` endpoint.

```json
GET https://api.didomi.io/metadata/purposes/{purposeId}?organization_id=YOUR_ORG_ID

{
  "id": "string",
  "description": "String",
  "details": "String",
  "reference": "String",
  "organization_id": "string",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "metadata": {},  
  "namespaces": {
    "iab": "string",
    "iab2": "string",
    "didomi": "string",
    "custom": "string"
  }
}
```

## Update a purpose

To update a purpose, you need to send a **PATCH** request on `/metadata/purpose/id` endpoint.

```json
PATCH https://api.didomi.io/metadata/purposes/{purposeId}?organization_id=YOUR_ORG_ID

{
  "description": "String",
  "details": "String",
  "reference": "String",
  "organization_id": "string",
  "metadata": {},  
  "namespaces": {
    "iab": "string",
    "iab2": "string",
    "didomi": "string",
    "custom": "string"
  }
}
```

## Delete a purpose

To delete a purpose, you need to send a **DELETE** request on `/metadata/purpose/id` endpoint.

```
DELETE https://api.didomi.io/metadata/purposes/{purposeId}?organization_id=YOUR_ORG_ID
```