> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datanumia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add, modify and delete users

The client subscription, modification and termination process is done at the Client's site level.

<Frame caption="Service offers and functionalities">
  <img src="https://mintcdn.com/datanumia/kj1PynBFje6urg6J/images/service-offers-and-functionalities.png?fit=max&auto=format&n=kj1PynBFje6urg6J&q=85&s=967006e6805fac136f05d5442cd09134" alt="service-offers-and-functionalities.png" width="2000" height="1920" data-path="images/service-offers-and-functionalities.png" />
</Frame>

**Service Offer**: It is a set of functionalities that the end user will be able to use after a successful subscription.

**Subscription**: Process which consists of creating the client, their sites and subscribing them to the requested service offers in order to give them access to the different functionalities of Home.

**Termination**: Process which consists of terminating a site's subscription to a Home service offer and cutting off its access to the functionality and ultimately deleting the related data following the personal data retention policy

## Site Lifecycle

<Frame caption="Site lifecycle">
  <img src="https://mintcdn.com/datanumia/kj1PynBFje6urg6J/images/site-lifecycle.png?fit=max&auto=format&n=kj1PynBFje6urg6J&q=85&s=443f410c8fe36d56fdb33742eb96d13e" alt="site-lifecycle.png" width="3360" height="1680" data-path="images/site-lifecycle.png" />
</Frame>

## Services

### General principles

Our client and site subscription, modification and termination services are built around the "cancel and replace" principle.

We ask a "photo" of the desired state of the client and its sites. Then we execute all the subscription, modification and termination operations needed to synchronize their state with the one we received.

<Frame caption="Client and site decision">
  <img src="https://mintcdn.com/datanumia/kj1PynBFje6urg6J/images/client-and-site-decision-flow.png?fit=max&auto=format&n=kj1PynBFje6urg6J&q=85&s=83320f1eacca964e7cac703667af8299" alt="client-and-site-decision-flow.png" width="3008" height="3800" data-path="images/client-and-site-decision-flow.png" />
</Frame>

### Unit mode

This method enables to manage subscription, modification and termination of one client and its sites individually.

### Mass mode

This method allows bulk process of subscription, modification or termination of multiple client and sites at a large scale through the use of **JSON files** containing **requests**. A **request** contains the information of the client and its sites.

These **JSON files** are transmitted in a compressed **archive** which is processed asynchronously by a **job**.

#### Job status specification

Once an archive sent, you can monitor the progress of a **job** and access a detailed report on all the **requests** whether the job successfuly finished or encountered errors.

A **job** status will help you follow its processing

<Frame caption="Archive request lifecycle">
  <img src="https://mintcdn.com/datanumia/kj1PynBFje6urg6J/images/archive-request-lifecycle.png?fit=max&auto=format&n=kj1PynBFje6urg6J&q=85&s=e8dff2c3377ee18706e3da334e52765f" alt="archive-request-lifecycle.png" width="3568" height="2500" data-path="images/archive-request-lifecycle.png" />
</Frame>

| Status | Description |
| - | - |
| `SUBMITTED` | The archive is received but processing has not started |
| `IN_PROGRESS` | The archive is being processed |
| `DONE` | Archive processing is completed without errors and a detailed report on each request is accessible |
| `ERROR` | Archive processing is completed but has encountered at least one functional error. Their details are available in the detailed report. Actions on the client side is necessary to correct them and rerun the corresponding requests |
| `INTERNAL_ERROR` | Archive processing stopped mid-process for an unknown reason. Actions on Datanumia's side are necessary to correct them. The corresponding archive should be sent again for a complete retry. |
| `TIMEOUT` | Archive processing stopped mid-process because of a slow processing time. Actions on Datanumia's side is necessary to correct them. The corresponding archive should be sent again for a complete retry. |

## Subscription expected information

### Client

| Information | Description | Required |
| - | - | - |
| `Client identifier` | Your client identifier or Home generated identifier depending if the client is new or not | Yes |
| `Title` | Title of the client | No |
| `First name` | First name of the client | No |
| `Last name` | Last name of the client | No |
| `Mobile` | Mobile number of the client | No |
| `Email` | Email of the client | No |
| `Street information` | Street name, numbers and additional informaitons of the client's main address | No |
| `Zip code` | Zip code of the client's main address | No |
| `City` | City of the client's main address | No |
| `Country` | Country of the client's main address | No |

### Site

#### Site main information

| Information | Description | Required |
| - | - | - |
| `Site identifier` | Your client identifier or Home generated identifier depending if the site is new or not | Yes |
| `Street information` | Street name, numbers and additional informaitons of the site address | No |
| `Zip code` | Zip code of the site address | Yes |
| `City` | City of the site address | No |
| `Country` | Country of the site address | Yes |

#### Point of delivery

| Information | Description | Required |
| - | - | - |
| `Point of delivery identifier` | Identifier of the point of delivery managed by the DSO | Yes |
| `Meter Type` | Detail on the point of delivery meter type | Yes |

#### Service offer

| Information | Description | usage | Required |
| - | - | - | - |
| `Service Offer Code` | Identifier of the service offer to subscribe to | Site access to Home functionalities | Yes |

### Example of a JSON payload

```json theme={null}
{
  "ts": "2020-07-21T17:32:28Z",
  "person": {
    "personId": "my_cleint_id",
    "content": {
      "title": "Mme",
      "firstName": "Jane",
      "lastName": "Doe",
      "address": {
        "streetNumber": "4 bis",
        "streetName": "place des vosges",
        "streetAdditionalInfo": "BP 90137 44701",
        "locationAdditionalInfo": "Batiment B",
        "zipCode": "92400",
        "city": "Courbevoie",
        "country": "France"
      },
      "mobile": "+33638854792",
      "email": "janedoe@datanumia.com"
    }
  },
  "sites": [
    {
      "siteId": "my_site_id",
      "content": {
        "address": {
          "streetNumber": "4 bis",
          "streetName": "place des vosges",
          "streetAdditionalInfo": "BP 90137 44701",
          "locationAdditionalInfo": "Batiment B",
          "zipCode": "92400",
          "city": "Courbevoie",
          "country": "France"
        },
        "pointsOfDelivery": {
          "elec": [
            {
              "elecPointOfDeliveryId": "5333333371",
              "meter": {
                "type": "SMART_METER
              }
            }
          ]
        },
        "serviceOffers": [
          {
            "code": "OF001"
          },
          {
            "code": "OF002"
          }
        ]
      }
    }
  ]
}
```