> ## 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. # Submit a job > Allows you to **submit an archive** containing sites' contracts (*see details in "Body" section*). Once the archive is **sent**, it is **decompressed** and each file it contains is processed. No order is guaranteed for the file processing order nor the order of processing of requests within a file. Contracts **processing** for a given pod is **atomic** within a file meaning that validation rules described in the corresponding unitary **operations are evaluated before inserting** the contracts for a given pod. Since the **processing is asynchronous** (archive storage, then processing to avoid blocking the API), this **endoint returns a URL to access the job status** through a details report. For the same reason, errors are not returned via an HTTP code but via this report. ## OpenAPI ````yaml /api-reference/contracts.yaml post /contracts-jobs openapi: 3.0.3 info: title: Contracts lifecycle description: > This API manages the lifecycle of contracts associated to a PoD. Contract key concepts: - A contract is applicable starting it ts value and ends with the next contract beginning - The definition of an existing contract can be updated using the ts and generationTs fields 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: /contracts-jobs: post: tags: - bulk mode contracts summary: Submit a job description: >- Allows you to **submit an archive** containing sites' contracts (*see details in "Body" section*). Once the archive is **sent**, it is **decompressed** and each file it contains is processed. No order is guaranteed for the file processing order nor the order of processing of requests within a file. Contracts **processing** for a given pod is **atomic** within a file meaning that validation rules described in the corresponding unitary **operations are evaluated before inserting** the contracts for a given pod. Since the **processing is asynchronous** (archive storage, then processing to avoid blocking the API), this **endoint returns a URL to access the job status** through a details report. For the same reason, errors are not returned via an HTTP code but via this report. operationId: bulkContractsOperation requestBody: content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: >- A .tar.gz archive containing the The json files to be processed. required: true description: "Only the .tar.gz archive format is valid. The archive must contain between 1 and 10 JSON files and its size cannot exceed 5 MB. Each JSON file can contain up to 10 000 contracts.\r\n\r\nExpected object formats are :\r\n\r\n```withDatanumiaId json_schema\r\n{\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"contracts\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"siteId\": {\r\n \"type\": \"string\",\r\n \"description\": \"Site identifier provided by Datanumia\",\r\n \"example\": \"site-3000\"\r\n },\r\n \"podId\": {\r\n \"type\": \"string\",\r\n \"description\":\"Identifier of the point of delivery\",\r\n \"example\":\"pdl-38\"\r\n },\r\n \"fluid\": {\r\n \"type\": \"string\",\r\n \"description\": \"Type of energy covered by the contract: electricity or gas\",\r\n \"enum\": [\"elec\",\"gas\"]\r\n },\r\n \"ts\": {\r\n \"type\": \"string\",\r\n \"description\": \"Effective date of the contract, whether it is a new contract or an amendment to a previously submitted contract. \\n\\rThe supported format is as defined by RFC 3339, section 5.6 restricted to : full-date'T'partial-time'Z'\",\r\n \"example\":\"2021-07-21T22:00:00Z\"\r\n },\r\n \"generationTs\": {\r\n \"type\": \"string\",\r\n \"description\":\"Date used to historize contracts for a given ts. \\n\\r The supported format is as defined by RFC 3339, section 5.6 restricted to : full-date'T'partial-time'Z'\",\r\n \"example\": \"2022-05-17T14:28:37Z\"\r\n },\r\n \"supplyContractParameters\": {\r\n \"type\": \"object\",\r\n \"description\": \"Parameters and values describing the contract. This list may vary depending on Marketer's configuration\",\r\n \"example\" : \"{ \\\"TARIFF\\\": \\\"ELEC_PE_VERT\\\",\r\n \\\"TARIFF_OPTION\\\": \\\"HPHC\\\",\r\n \\\"SUBSCRIBED_POWER\\\": \\\"9\\\",\r\n \\\"MILLESIME\\\": \\\"2\\\"\r\n }\"\r\n },\r\n \"tariffCalendar\": {\r\n \"type\": \"array\",\r\n \"description\": \"Distributor calendar associated to the client's site. Specific to electricity contracts.\",\r\n \"items\": {\r\n \"type\":\"object\",\r\n \"properties\" : {\r\n \"periods\":{\r\n \"type\": \"array\",\r\n \"description\": \"Period for which the calendar is defined : \\n\\r - If tariffCalendar contains more than one object, then a period must be defined for each. \\n\\r - Periods defined within tariffCalendar must cover a full year without overlap \\n\\r - The beginDate must precede the endDate \",\r\n \"items\": [\r\n {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"beginDate\": {\r\n \"type\": \"string\",\r\n \"description\": \"Start date of the period. This date is included.\\n\\r The supported format is as defined by RFC 3339 : --MM:DD\",\r\n \"example\": \"--01-01\"\r\n },\r\n \"endDate\": {\r\n \"type\": \"string\",\r\n \"description\": \"End date of the period. This date is included.\\n\\r The supported format is as defined by RFC 3339 : --MM:DD\",\r\n \"example\": \"--12-31\"\r\n }\r\n },\r\n \"required\": [\r\n \"beginDate\",\r\n \"endDate\"\r\n ]\r\n }\r\n ]\r\n },\r\n \"timeRangeByLabels\": {\r\n \"type\": \"array\",\r\n \"description\": \"Defines the period of activity for a list of labels\",\r\n \"items\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"label\": {\r\n \"type\": \"string\",\r\n \"description\": \"Label name (= Dial name). By convention, value is \\\"cadran1\\\" \",\r\n \"example\": \"cadran1\",\r\n },\r\n \"ranges\": {\r\n \"type\": \"array\",\r\n \"description\": \"Time ranges during which the label is active\",\r\n \"items\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"begin\": {\r\n \"type\": \"string\",\r\n \"description\": \"Begin time in HH:mm:ss format\",\r\n \"example\": \"00:00:00\"\r\n },\r\n \"end\": {\r\n \"type\": \"string\",\r\n \"description\": \"End time in HH:mm:ss format\",\r\n \"example\": \"06:00:00\"\r\n }\r\n },\r\n \"required\": [\r\n \"begin\",\r\n \"end\"\r\n ]\r\n }\r\n }\r\n },\r\n \"required\": [\r\n \"label\",\r\n \"ranges\"\r\n ]\r\n }\r\n }\r\n },\r\n \"required\": [\r\n \"timeRangeByLabels\"\r\n ]\r\n }\r\n }\r\n },\r\n \"required\": [\r\n \"siteId\",\r\n \"podId\",\r\n \"fluid\",\r\n \"ts\",\r\n \"generationTs\",\r\n \"supplyContractParameters\"\r\n ]\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n```WithCustomerIds json_schema\r\n{\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"contracts\": {\r\n \"type\": \"array\",\r\n \"items\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"personCustomerId\": {\r\n \"type\": \"string\",\r\n \"description\": \"Person identifier provided by the Marketer\",\r\n \"example\": \"bp-3000\"\r\n },\r\n \"siteCustomerId\": {\r\n \"type\": \"string\",\r\n \"description\": \"Site identifier provided by the Marketer\",\r\n \"example\": \"site-3000\"\r\n },\r\n \"podId\": {\r\n \"type\": \"string\",\r\n \"description\":\"Identifier of the point of delivery\",\r\n \"example\":\"pdl-38\"\r\n },\r\n \"fluid\": {\r\n \"type\": \"string\",\r\n \"description\": \"Type of energy covered by the contract: electricity or gas\",\r\n \"enum\": [\"elec\",\"gas\"]\r\n },\r\n \"ts\": {\r\n \"type\": \"string\",\r\n \"description\": \"Effective date of the contract, whether it is a new contract or an amendment to a previously submitted contract. \\n\\rThe supported format is as defined by RFC 3339, section 5.6 restricted to : full-date'T'partial-time'Z'\",\r\n \"example\":\"2021-07-21T22:00:00Z\"\r\n },\r\n \"generationTs\": {\r\n \"type\": \"string\",\r\n \"description\":\"Date used to historize contracts for a given ts. \\n\\r The supported format is as defined by RFC 3339, section 5.6 restricted to : full-date'T'partial-time'Z'\",\r\n \"example\": \"2022-05-17T14:28:37Z\"\r\n },\r\n \"supplyContractParameters\": {\r\n \"type\": \"object\",\r\n \"description\": \"Parameters and values describing the contract. This list may vary depending on Marketer's configuration\",\r\n \"example\" : \"\\\"supplyContractParameters\\\": { \\\"TARIFF\\\": \\\"ELEC_PE_VERT\\\",\r\n \\\"TARIFF_OPTION\\\": \\\"HPHC\\\",\r\n \\\"SUBSCRIBED_POWER\\\": \\\"9\\\",\r\n \\\"MILLESIME\\\": \\\"2\\\"\r\n }\\\"\"\r\n },\r\n \"tariffCalendar\": {\r\n \"type\": \"array\",\r\n \"description\": \"Distributor calendar associated to the client's site. Specific to electricity contracts.\",\r\n \"items\": {\r\n \"type\":\"object\",\r\n \"properties\" : {\r\n \"periods\":{\r\n \"type\": \"array\",\r\n \"description\": \"Period for which the calendar is defined : \\n\\r - If tariffCalendar contains more than one object, then a period must be defined for each. \\n\\r - Periods defined within tariffCalendar must cover a full year without overlap \\n\\r - The beginDate must precede the endDate \",\r\n \"items\": [\r\n {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"beginDate\": {\r\n \"type\": \"string\",\r\n \"description\": \"Start date of the period. This date is included.\\n\\r The supported format is as defined by RFC 3339 : --MM:DD\",\r\n \"example\": \"--01-01\"\r\n },\r\n \"endDate\": {\r\n \"type\": \"string\",\r\n \"description\": \"End date of the period. This date is included.\\n\\r The supported format is as defined by RFC 3339 : --MM:DD\",\r\n \"example\": \"--12-31\"\r\n }\r\n },\r\n \"required\": [\r\n \"beginDate\",\r\n \"endDate\"\r\n ]\r\n }\r\n ]\r\n },\r\n \"timeRangeByLabels\": {\r\n \"type\": \"array\",\r\n \"description\": \"Defines the period of activity for a list of labels\",\r\n \"items\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"label\": {\r\n \"type\": \"string\",\r\n \"description\": \"Label name (= Dial name). By convention, value is \\\"cadran1\\\" \",\r\n \"example\": \"cadran1\",\r\n },\r\n \"ranges\": {\r\n \"type\": \"array\",\r\n \"description\": \"Time ranges during which the label is active\",\r\n \"items\": {\r\n \"type\": \"object\",\r\n \"properties\": {\r\n \"begin\": {\r\n \"type\": \"string\",\r\n \"description\": \"Begin time in HH:mm:ss format\",\r\n \"example\": \"00:00:00\"\r\n },\r\n \"end\": {\r\n \"type\": \"string\",\r\n \"description\": \"End time in HH:mm:ss format\",\r\n \"example\": \"06:00:00\"\r\n }\r\n },\r\n \"required\": [\r\n \"begin\",\r\n \"end\"\r\n ]\r\n }\r\n }\r\n },\r\n \"required\": [\r\n \"label\",\r\n \"ranges\"\r\n ]\r\n }\r\n }\r\n },\r\n \"required\": [\r\n \"timeRangeByLabels\"\r\n ]\r\n }\r\n }\r\n },\r\n \"required\": [\r\n \"siteCustomerId\",\r\n \"personCustomerId\",\r\n \"podId\",\r\n \"fluid\",\r\n \"ts\",\r\n \"generationTs\",\r\n \"supplyContractParameters\"\r\n ]\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n" responses: '200': description: >- Returns a job tracking URL \"GET /indexes-collect-jobs/{job-id}\" to access a detailed execution report. content: application/json: schema: $ref: '#/components/schemas/MassContractRequestsResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: {} '413': description: "Request Entity Too Large\r\n\r\nWhen archive payload is > 5 MB" '500': description: Server error content: {} security: - Bearer: - home:elec-contracts:jobs:write home:gas-contracts:jobs:write components: schemas: MassContractRequestsResponse: description: Return a job id that can be used to track the job execution status type: object properties: _links: $ref: '#/components/schemas/JobLinks' ErrorResponse: required: - errorCode - errorDescription type: object properties: errorCode: description: The error code. type: string errorDescription: type: string description: The error description description: ErrorResponse JobLinks: required: - self type: object properties: self: $ref: '#/components/schemas/JobLinkSelf' JobLinkSelf: required: - href type: object properties: href: type: string example: https:///contracts-jobs/{job-id} securitySchemes: Bearer: type: http scheme: bearer ````