> ## 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. # Synchronize a person > With this endpoint you are able to manage the **person** and its **site** lifecycle: Handle all the **subscribtion** use cases: - Subscribe a new **person** and its **sites** to a **service offer** - Subscribe a new **site** of an existing **person** to a **service offer** - Subscribe a new **service offer** to an existing **site** of an existing person Handle the information **modification** of the **person** or its **sites** use cases: - Update **person** personal information - Update **sites** informations Handle all the **termination** use cases: - Terminate a specific **site**'s **service offer** - Terminate one of the **person**'s **site**, meaning terminating all the **site**'s **service offers** - Terminate of all the person's sites, meaning terminating all the **service offers** of the **person**'s **sites** ## General principles This synchronization API asks for a "picture" of the desired state of the **person**, its **sites** and **service offers**. Then we execute all the subscription, modification and termination operations to synchronize HOME state for this **person** with the one sent in the body. At the **first subscribtion** of a new **person** or a new **site**, **HOME identifiers** are sent back in the response body. They are needed to indentify the **person** and its **sites** in our APIs. ## Lifecycle example Let's start from an initial state and subscribe a new **person** with two **sites** to two **service offers** by calling the `POST person/synchronization`. Any new **person** or **site** must be subscribed with custumer Ids. ```json { "ts": "2024-03-09T17:32:28Z", "person": { "personCustomerId": "personCustomerId", "content": { "mobile": "+33123456789" //person personnal informations } }, "sites": [ { "siteCustomerId": "siteCustomerId_1", "content": { "address": { //site specific adress information }, "pointsOfDelivery": { //elec and gas point of delivery information }, "serviceOffers": [ { "code": "OF001" }, { "code": "OF002" } ] } }, { "siteCustomerId": "siteCustomerId_2", "content": { "address": { //site specific adress informaton }, "pointsOfDelivery": { //elec and gas point of delivery information }, "serviceOffers": [ { "code": "OF001" }, { "code": "OF002" } ] } } ] } ``` Response: ```json { "ts": "2024-03-09T17:32:28Z", "person": { "personId""randomPersonId" //... }, "sites": [ { "siteId": "randomSiteId_1" //... }, { "siteId": "randomSiteId_2" //... } ] } ``` After the first **subscription**, these identifiers will be required to use **person** and **site** services such as the `POST person/synchronization` and almost any other HOME API Then, let's **terminate** the **person** second **site** with the `POST person/synchronization` by removing it from the site list. This means we terminate all the **site**'s **service offers**. ```json { "ts": "2024-03-09T17:32:28Z", "person": { "personId": "randomPersonId", "content": { "mobile": "+33123456789" //person personnal informations } }, "sites": [ { "siteId": "randomSiteId_1", "content": { "address": { //site specific adress informaton }, "pointsOfDelivery": { //elec and gas point of delivery information }, "serviceOffers": [ { "code": "OF001" }, { "code": "OF002" } ] } } ] } ``` We can also **terminate** the second **service offer** of the first **site** with the `POST person/synchronization` by removing the **service offer** code from the **service offer** list. ```json { "ts": "2024-03-09T17:32:28Z", "person": { "personId": "randomPersonId", "content": { "mobile": "+33123456789" //person personnal informations } }, "sites": [ { "siteId": "randomSiteId_1", "content": { "address": { //site specific adress informaton }, "pointsOfDelivery": { //elec and gas point of delivery information }, "serviceOffers": [ { "code": "OF001" } ] } } ] } ``` Until now, we did each **termination** operation invividualy. But we could of done them in the same `POST person/synchronization` by removing the second **site** from the **site** list AND removing the second **service offer** from the first **site** in the same body, resulting to posting the last example. Given this **person** state, let's see how to **subscribe** a new **site** and **modify** the **person** mobile phone number which is, for now, set to +33123456789. Be carfull, you still need to send all the **person** and **site** other informations. Any missing field will be considered as a modification request from your side. ```json { "ts": "2024-03-09T17:32:28Z", "person": { "personId": "randomPersonId", "content": { "mobile": "+33000000000" //person personnal informations } }, "sites": [ { "siteId": "randomSiteId_1", "content": { "address": { //site specific adress informaton }, "pointsOfDelivery": { //elec and gas point of delivery information }, "serviceOffers": [ { "code": "OF001" } ] } }, { "siteCustomerId": "SiteCustomerId_3", "content": { "address": { //site specific adress informaton }, "pointsOfDelivery": { //elec and gas point of delivery information }, "serviceOffers": [ { "code": "OF001" }, { "code": "OF002" }, ] } } ] } ``` Response ```json { "ts": "2024-03-09T17:32:28Z", "person": { "personId""randomPersonId" //... }, "sites": [ { "siteId": "randomSiteId_1", //... }, { "siteId": "randomSiteId_3", //... } ] } ``` If you wanted to delete the **person** mobile phone number, you could of removed it from the body. In order to **terminate** the **person** with all its **sites**, you can use the `POST person/synchronization` by sending an empty **site** list which means the desired state of the **person** is a **person** with no **site** subscribed to any **service offer**. ```json { "ts":"2024-03-09T17:32:28Z", "person":{ "personId":"randomPersonId", "content":{ "mobile":"+33000000000" } }, "sites":[] } ``` ## Errors Error code | Description ----------|--------- **FIELD_IS_INVALID** | A field content do not match the regex specified in the documentation **FIELD_IS_MANDATORY** | A required field is missing **INTERNAL_ERROR** | Requires an investigation to restore the service and/or correct the anomaly on Datanumia's side **INVALID_SERVICE_OFFER_CODE** | One of a service offer code does not match the configured service offers **OFFER_DUPLICATED** | The serviceOffers list contains the same offer code multiple times **OFFER_MANDATORY** | The serviceOffers list is missing in the site object **OPERATION_ALREADY_IN_PROGRESS** | Two requests on the same person or site are executed concurrently. Do not send two requests on the same person or site in the same archive **OPERATION_NOT_SUPPORTED** | A modification, termination or subscription operation is not supported **SITE_DUPLICATED** | A person's site list contains the same site multiple times **SITE_MANDATORY** | The list of sites is empty or missing for a person not yet subscribed ## OpenAPI ````yaml /api-reference/persons-sites-service-offers.yaml post /person/synchronization openapi: 3.0.3 info: title: Person, Site and Service Offer lifecycle description: > This API manages the lifecycle of persons, sites and service offers as described [here](https://datanumia.stoplight.io/docs/DatanumiaHome/YXBpOjQ0ODQzMjMy-person-site-and-service-offer-lifecycle) Please refer to the following link to get a better understanding of the [core concepts](https://datanumia.stoplight.io/docs/DatanumiaHome/ZG9jOjM4MDg2NDE5-core-concepts) of the Home platform. Important notice with regard to those APIs: - When subscribing or deleting multiple subscribed offers on a site or subscribed offers on multiple sites please provide all sites and subscribe offer data in a single POST subscriptions call. - They are idempotent. Launching multiple times the same operation will lead to the same result - They require a complete snapshot of all the objects involved in the operation. Those new objects overwrite the existing one. In other words, missing properties will be considered empty or null when operations will be executed on existing person/site objects termsOfService: TODO contact: email: api@datanumia.com version: 2.0.0 servers: - url: https://api.home.datanumia.com/api/v2 description: Production Server security: [] paths: /person/synchronization: post: tags: - Unitary mode summary: Synchronize a person description: "With this endpoint you are able to manage the **person** and its **site** lifecycle:\r\n\r\nHandle all the **subscribtion** use cases:\r\n- Subscribe a new **person** and its **sites** to a **service offer**\r\n- Subscribe a new **site** of an existing **person** to a **service offer**\r\n- Subscribe a new **service offer** to an existing **site** of an existing person\r\n\r\nHandle the information **modification** of the **person** or its **sites** use cases:\r\n- Update **person** personal information\r\n- Update **sites** informations\r\n\r\nHandle all the **termination** use cases:\r\n- Terminate a specific **site**'s **service offer**\r\n- Terminate one of the **person**'s **site**, meaning terminating all the **site**'s **service offers**\r\n- Terminate of all the person's sites, meaning terminating all the **service offers** of the **person**'s **sites**\r\n\r\n## General principles\r\nThis synchronization API asks for a \"picture\" of the desired state of the **person**, its **sites** and **service offers**. \r\nThen we execute all the subscription, modification and termination operations to synchronize HOME state for this **person** with the one sent in the body.\r\n\r\nAt the **first subscribtion** of a new **person** or a new **site**, **HOME identifiers** are sent back in the response body.\r\nThey are needed to indentify the **person** and its **sites** in our APIs.\r\n\r\n## Lifecycle example\r\nLet's start from an initial state and subscribe a new **person** with two **sites** to two **service offers** by calling the `POST person/synchronization`.\r\nAny new **person** or **site** must be subscribed with custumer Ids.\r\n```json\r\n{\r\n \"ts\": \"2024-03-09T17:32:28Z\",\r\n \"person\": {\r\n \"personCustomerId\": \"personCustomerId\",\r\n \"content\": {\r\n \"mobile\": \"+33123456789\"\r\n //person personnal informations\r\n }\r\n },\r\n \"sites\": [\r\n {\r\n \"siteCustomerId\": \"siteCustomerId_1\",\r\n \"content\": {\r\n \"address\": {\r\n //site specific adress information\r\n },\r\n \"pointsOfDelivery\": {\r\n //elec and gas point of delivery information\r\n },\r\n \"serviceOffers\": [\r\n {\r\n \"code\": \"OF001\"\r\n },\r\n {\r\n \"code\": \"OF002\"\r\n }\r\n ]\r\n }\r\n },\r\n {\r\n \"siteCustomerId\": \"siteCustomerId_2\",\r\n \"content\": {\r\n \"address\": {\r\n //site specific adress informaton\r\n },\r\n \"pointsOfDelivery\": {\r\n //elec and gas point of delivery information\r\n },\r\n \"serviceOffers\": [\r\n {\r\n \"code\": \"OF001\"\r\n },\r\n {\r\n \"code\": \"OF002\"\r\n }\r\n ]\r\n }\r\n }\r\n ]\r\n}\r\n```\r\nResponse: \r\n```json\r\n{\r\n \"ts\": \"2024-03-09T17:32:28Z\",\r\n \"person\": {\r\n \"personId\"\"randomPersonId\"\r\n //...\r\n },\r\n \"sites\": [\r\n {\r\n \"siteId\": \"randomSiteId_1\"\r\n //...\r\n },\r\n {\r\n \"siteId\": \"randomSiteId_2\"\r\n //...\r\n }\r\n ]\r\n}\r\n\r\n```\r\nAfter the first **subscription**, these identifiers will be required to use **person** and **site** services such as the `POST person/synchronization` and almost any other HOME API\r\n\r\nThen, let's **terminate** the **person** second **site** with the `POST person/synchronization` by removing it from the site list. This means we terminate all the **site**'s **service offers**.\r\n```json\r\n{\r\n \"ts\": \"2024-03-09T17:32:28Z\",\r\n \"person\": {\r\n \"personId\": \"randomPersonId\",\r\n \"content\": {\r\n \"mobile\": \"+33123456789\"\r\n //person personnal informations\r\n }\r\n },\r\n \"sites\": [\r\n {\r\n \"siteId\": \"randomSiteId_1\",\r\n \"content\": {\r\n \"address\": {\r\n //site specific adress informaton\r\n },\r\n \"pointsOfDelivery\": {\r\n //elec and gas point of delivery information\r\n },\r\n \"serviceOffers\": [\r\n {\r\n \"code\": \"OF001\"\r\n },\r\n {\r\n \"code\": \"OF002\"\r\n }\r\n ]\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\nWe can also **terminate** the second **service offer** of the first **site** with the `POST person/synchronization` by removing the **service offer** code from the **service offer** list.\r\n\r\n```json\r\n{\r\n \"ts\": \"2024-03-09T17:32:28Z\",\r\n \"person\": {\r\n \"personId\": \"randomPersonId\",\r\n \"content\": {\r\n \"mobile\": \"+33123456789\"\r\n //person personnal informations\r\n }\r\n },\r\n \"sites\": [\r\n {\r\n \"siteId\": \"randomSiteId_1\",\r\n \"content\": {\r\n \"address\": {\r\n //site specific adress informaton\r\n },\r\n \"pointsOfDelivery\": {\r\n //elec and gas point of delivery information\r\n },\r\n \"serviceOffers\": [\r\n {\r\n \"code\": \"OF001\"\r\n }\r\n ]\r\n }\r\n }\r\n ]\r\n}\r\n```\r\n\r\nUntil now, we did each **termination** operation invividualy. But we could of done them in the same `POST person/synchronization` by removing the second **site** from the **site** list AND removing the second **service offer** from the first **site** in the same body, resulting to posting the last example.\r\n\r\nGiven this **person** state, let's see how to **subscribe** a new **site** and **modify** the **person** mobile phone number which is, for now, set to +33123456789.\r\n\r\nBe carfull, you still need to send all the **person** and **site** other informations. Any missing field will be considered as a modification request from your side. \r\n\r\n```json\r\n{\r\n \"ts\": \"2024-03-09T17:32:28Z\",\r\n \"person\": {\r\n \"personId\": \"randomPersonId\",\r\n \"content\": {\r\n \"mobile\": \"+33000000000\"\r\n //person personnal informations\r\n }\r\n },\r\n \"sites\": [\r\n {\r\n \"siteId\": \"randomSiteId_1\",\r\n \"content\": {\r\n \"address\": {\r\n //site specific adress informaton\r\n },\r\n \"pointsOfDelivery\": {\r\n //elec and gas point of delivery information\r\n },\r\n \"serviceOffers\": [\r\n {\r\n \"code\": \"OF001\"\r\n }\r\n ]\r\n }\r\n },\r\n {\r\n \"siteCustomerId\": \"SiteCustomerId_3\",\r\n \"content\": {\r\n \"address\": {\r\n //site specific adress informaton\r\n },\r\n \"pointsOfDelivery\": {\r\n //elec and gas point of delivery information\r\n },\r\n \"serviceOffers\": [\r\n {\r\n \"code\": \"OF001\"\r\n },\r\n {\r\n \"code\": \"OF002\"\r\n },\r\n \r\n ]\r\n }\r\n }\r\n ]\r\n}\r\n```\r\nResponse\r\n```json\r\n{\r\n \"ts\": \"2024-03-09T17:32:28Z\",\r\n \"person\": {\r\n \"personId\"\"randomPersonId\"\r\n //...\r\n },\r\n \"sites\": [\r\n {\r\n \"siteId\": \"randomSiteId_1\",\r\n //...\r\n },\r\n {\r\n \"siteId\": \"randomSiteId_3\",\r\n //...\r\n }\r\n ]\r\n}\r\n\r\n```\r\nIf you wanted to delete the **person** mobile phone number, you could of removed it from the body.\r\n\r\nIn order to **terminate** the **person** with all its **sites**, you can use the `POST person/synchronization` by sending an empty **site** list which means the desired state of the **person** is a **person** with no **site** subscribed to any **service offer**.\r\n```json\r\n{\r\n\t\"ts\":\"2024-03-09T17:32:28Z\",\r\n\t\"person\":{\r\n\t \"personId\":\"randomPersonId\",\r\n\t \"content\":{\r\n\t\t \"mobile\":\"+33000000000\"\r\n\t }\r\n\t},\r\n\t\"sites\":[]\r\n }\r\n\r\n```\r\n\r\n## Errors\r\n\r\nError code | Description \r\n----------|---------\r\n**FIELD_IS_INVALID** | A field content do not match the regex specified in the documentation \r\n**FIELD_IS_MANDATORY** | A required field is missing\r\n**INTERNAL_ERROR** | Requires an investigation to restore the service and/or correct the anomaly on Datanumia's side\r\n**INVALID_SERVICE_OFFER_CODE** | One of a service offer code does not match the configured service offers \r\n**OFFER_DUPLICATED** | The serviceOffers list contains the same offer code multiple times\r\n**OFFER_MANDATORY** | The serviceOffers list is missing in the site object\r\n**OPERATION_ALREADY_IN_PROGRESS** | Two requests on the same person or site are executed concurrently. Do not send two requests on the same person or site in the same archive \r\n**OPERATION_NOT_SUPPORTED** | A modification, termination or subscription operation is not supported\r\n**SITE_DUPLICATED** | A person's site list contains the same site multiple times\r\n**SITE_MANDATORY** | The list of sites is empty or missing for a person not yet subscribed\r\n\r\n" operationId: processSubscriptions_1 parameters: - name: offer-family-id in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SMTRequest' required: true responses: '200': description: person updated content: '*/*': schema: $ref: '#/components/schemas/SMTRequest' '422': description: Unprocessable Content content: application/json: schema: $ref: '#/components/schemas/Problem' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/Problem' components: schemas: SMTRequest: required: - person - sites - ts type: object properties: ts: type: string description: > Timestamp of the request as defined by RFC 3339, section 5.6 using the following format: full-date'T'partial-time'Z' format: date-time example: '2017-07-21T17:32:28Z' person: $ref: '#/components/schemas/PersonDataWithCustomerId' sites: minItems: 0 maxItems: 10 type: array items: $ref: '#/components/schemas/SiteDataWithCustomerId' Problem: type: object properties: type: type: string format: uri title: type: string errors: type: array items: $ref: '#/components/schemas/Error' PersonDataWithCustomerId: description: The Person type: object properties: personCustomerId: type: string description: Your person identifier. This id is unique within your persons. pattern: ^([a-zA-Z0-9_-]{0,20})$ example: person-45634 personId: type: string description: Datanumia person identifier content: $ref: '#/components/schemas/PersonContent' SiteDataWithCustomerId: description: The Person's site. type: object properties: siteCustomerId: type: string description: Your site identifier. This id is unique within your sites. pattern: ^([a-zA-Z0-9_-]{0,50})$ example: site-45634 siteId: type: string description: Datanumia site identifier content: $ref: '#/components/schemas/SiteContentWithServiceOffers' Error: type: object properties: code: type: string detail: type: string personCustomerId: type: string personId: type: string siteCustomerId: type: string siteId: type: string PersonContent: description: Data contained within a Person object type: object properties: title: type: string example: Mme pattern: | ^([\p{L}\s.,;-]{0,10})$ firstName: type: string pattern: | ^(.{0,100})$ example: Jane lastName: type: string pattern: | ^(.{0,100})$ example: Doe address: $ref: '#/components/schemas/PersonAddress' mobile: description: phone number in international format type: string pattern: | ^\+(?:[0-9] ?){6,14}[0-9]$ example: '+33638854792' email: type: string description: >- email address respecting the OWASP definition : https://owasp.org/www-community/OWASP_Validation_Regex_Repository pattern: > (?=.{0,100}$)(^[a-zA-Z0-9_+&*-]+(?:\.[a-zA-Z0-9_+&*-]+)*@(?:[a-zA-Z0-9-]+\.)+[a-zA-Z]{2,7}) example: api@datanumia.com SiteContentWithServiceOffers: type: object properties: address: $ref: '#/components/schemas/SiteAddressSMT' pointsOfDelivery: $ref: '#/components/schemas/PointsOfDelivery' serviceOffers: type: array minItems: 1 items: $ref: '#/components/schemas/ServiceOffer' PersonAddress: description: Address. type: object properties: streetNumberAndName: type: string example: 4 bis place des vosges pattern: ^(.{0,70})$ streetAdditionalInfo: type: string example: BP 90137 44701 pattern: ^(.{0,50})$ locationAdditionalInfo: type: string example: Batiment B pattern: ^(.{0,40})$ zipCode: type: string example: '92400' pattern: ^(.{0,20})$ city: type: string example: Courbevoie pattern: ^(.{0,50})$ country: type: string example: France pattern: ^(.{0,30})$ SiteAddressSMT: description: Site Address. required: - zipCode - country type: object properties: streetNumber: type: string example: 4 bis pattern: ^(.{0,40})$ streetName: type: string example: place des vosges pattern: ^(.{0,70})$ streetAdditionalInfo: type: string example: BP 90137 44701 pattern: ^(.{0,50})$ locationAdditionalInfo: type: string example: Batiment B pattern: ^(.{0,40})$ zipCode: type: string example: '92400' pattern: ^(.{0,20})$ city: type: string example: Courbevoie pattern: ^(.{0,50})$ country: type: string example: France pattern: ^(.{0,30})$ PointsOfDelivery: type: object properties: elec: type: array minItems: 0 maxItems: 1 items: $ref: '#/components/schemas/ElecPointOfDelivery' gas: type: array minItems: 0 maxItems: 1 items: $ref: '#/components/schemas/GasPointOfDelivery' ServiceOffer: description: A Home service offer. required: - code type: object properties: code: description: The code to use will be given by your CSM contact type: string pattern: ^([a-zA-Z0-9_-]{1,5})$ ElecPointOfDelivery: required: - elecPointOfDeliveryId - meter type: object properties: elecPointOfDeliveryId: type: string description: >- Identifier of the electricity point of Delivery as managed bu the DSO. pattern: ^([a-zA-Z0-9_-]{0,50})$ meter: $ref: '#/components/schemas/ElecMeter' GasPointOfDelivery: description: The required information about the gas meter. required: - gasPointOfDeliveryId - meter type: object properties: gasPointOfDeliveryId: type: string description: Identifier of the gas measurement point. meter: $ref: '#/components/schemas/GasPointOfDeliveryParameters' ElecMeter: description: The required information about the electrical meter. type: object required: - type properties: type: type: string description: Electrical meter type. enum: - ELECTRONIC_METER - ELECTROMAGNETIC_METER - SMART_METER - UNKNOWN id: type: string description: Identifier of the meter from the customer perspective. pattern: '[a-zA-Z0-9_-]+' firstCommunicationDate: type: string description: > Timestamp of the request as defined by RFC 3339, section 5.6 using the following format: full-date format: date example: '2017-07-21' pattern: \d{4}-\d{2}-\d{2} GasPointOfDeliveryParameters: description: The required information about the gas installation. type: object required: - type properties: type: type: string description: Gas meter type. enum: - MECHANICAL_METER - SMART_METER - UNKNOWN digitNumber: type: integer description: Maximum number of characters in an index reading. 6, by default. ````