# Create a contract

Use this workflow to create a Contract in UtilityCloud.

A Contract connects a Customer, an Account, one or more Products, and an Accounting Point. The endpoint can be used to create contracts for new or existing customers and accounts.

## Endpoint

```http
POST /v1/cm/contracts
```

## When to use

Use this workflow when an external system needs to create a new contract in UtilityCloud.

Typical use cases include:

- creating a contract from a CRM system
- creating a contract from a self-service or ordering solution
- creating a contract for a new customer
- creating a contract for an existing customer
- creating a contract on an existing Accounting Point
- creating multiple contracts for the same customer and account
- creating contracts with one primary product and optional add-on products

## Response

A valid request returns:

```http
202 Accepted
```

The operation is accepted for processing.

## Request structure

The request contains several parts. Some are mandatory and others are optional, depending on the contract flow, customer type, Account, Accounting Point, Products, Service Type, and tenant configuration.

```json
{
  "RequestId": "create a new GUID for each API request",
  "StartDate": "2026-06-01T22:00:00Z",
  "EndDate": null,
  "Customer": {},
  "CreateANewAccountForEachAccountingPoint": false,
  "Account": {},
  "AccountingPoint": {},
  "Products": [],
  "Options": {}
}
```

## Main request fields

| Field | Description |
|---|---|
| `RequestId` | Unique request id. Use a new GUID for each API request. Used for tracing and duplicate request handling. |
| `StartDate` | Start date for the contract. Must be midnight local time, represented as an ISO date/time with timezone. |
| `EndDate` | Optional end date for the contract. Use `null` or omit the property if the contract has no known end date. |
| `Customer` | Customer information. Can represent a new or existing customer. |
| `Account` | Account information. Can represent a new or existing Account. |
| `CreateANewAccountForEachAccountingPoint` | Indicates whether a new Account should be created for each Accounting Point. |
| `AccountingPoint` | Accounting Point information for the contract. |
| `AccountingPoints` | Alternative to `AccountingPoint` when creating contracts for multiple Accounting Points. |
| `Products` | Products that should be part of the contract. |
| `Options` | Optional processing options for the contract flow. |

## Example request

```json
{
  "RequestId": "7f4b0b8e-6d8b-4a72-9f2c-2f2d1fd8a001",
  "StartDate": "2026-06-01T22:00:00Z",
  "EndDate": null,
  "Customer": {
    "Identification": "31074355544",
    "GivenName": "Kari",
    "FamilyName": "Nordmann",
    "BirthDate": "31.07.1943",
    "Identifiers": [
      {
        "Source": "CRM",
        "Identification": "100157",
        "Description": "Customer number in CRM"
      }
    ]
  },
  "CreateANewAccountForEachAccountingPoint": false,
  "Account": {
    "Name": "Main account",
    "Addresses": [
      {
        "Type": "invoiceadr",
        "StreetName": "Example Street",
        "BuildingNumber": "1",
        "PostCode": "0123",
        "CityName": "Oslo",
        "CountryCode": "NO",
        "MunicipalityCode": "0101"
      }
    ],
    "Communication": [
      {
        "Channel": "Email",
        "Value": "customer@example.com",
        "Description": "Customer email"
      },
      {
        "Channel": "Mobile",
        "Value": "+4799988777",
        "Description": "Customer mobile"
      }
    ]
  },
  "AccountingPoint": {
    "Identification": "707057500012345678"
  },
  "Products": [
    {
      "ProductId": "6d1224116b6f42979815836fb343bb60",
      "ProductName": "Fastpris 1 år",
      "PrimaryProduct": true,
      "StartDate": "2026-06-01T22:00:00Z",
      "InteractivePrices": [
        {
          "Name": "i:Paaslag",
          "Value": "0.73"
        }
      ]
    }
  ],
  "Options": {
    "SkipRequestStartOfSupplyFromMarket": false,
    "SkipRequestAccountingPointCharacteristicsFromMarket": false,
    "SkipRequestAccountingPointMeterValuesFromMarket": false,
    "SkipCustomerConfirmation": true,
    "SkipCustomerCreditCheck": false
  }
}
```

## Customer and Account

The contract can be created for a new or existing customer.

For new customers, the contract is added to a new Account. For existing customers, the contract can be added to a new or existing Account.

The API looks for an existing Account and Customer using the following properties in this order:

1. `Account.Guid`
2. `Account.Identifiers`
3. `Customer.Guid`
4. `Customer.Identification`
5. `Customer.Identifiers`

If an existing customer is not found, a new customer is created with the information provided in the request.

If an existing Account or Customer is found, the provided properties may update the existing resource.

## Customer fields

| Field | Description |
|---|---|
| `Guid` | Optional UtilityCloud GUID for an existing customer. |
| `Identification` | National identity number for a private customer or organization number for a business customer. |
| `Name` | Company name. Used for business customers. |
| `GivenName` | Given name. Used for private customers. |
| `FamilyName` | Family name. Used for private customers. |
| `BirthDate` | Optional birth date for private customers. Format: `DD.MM.YYYY`. |
| `IsNonDigital` | Optional flag for private customers defined as non-digital. |
| `Identifiers` | External identifiers used for synchronization with other systems. |

## Account fields

| Field | Description |
|---|---|
| `Guid` | Optional UtilityCloud GUID for an existing Account. |
| `Name` | Optional Account name. |
| `Identifiers` | External identifiers used for synchronization with other systems. |
| `Addresses` | Invoice and/or postal address information. At least an invoice address is normally required. |
| `Communication` | Email, mobile, or phone information. |

## Account address fields

```json
{
  "Type": "invoiceadr",
  "StreetName": "Example Street",
  "BuildingNumber": "1",
  "PostofficeBox": "",
  "PostCode": "0123",
  "CityName": "Oslo",
  "CountryCode": "NO",
  "MunicipalityCode": "0101",
  "FloorIdentification": "",
  "RoomIdentification": "",
  "AttentionOf": "",
  "OnBehalfOf": "",
  "CareOf": ""
}
```

| Field | Description |
|---|---|
| `Type` | Address type. Use `invoiceadr` for invoice address or `postaladr` for postal address. |
| `StreetName` | Street name. |
| `BuildingNumber` | Building number, including any letters. |
| `PostofficeBox` | Post office box, if used instead of street address. |
| `PostCode` | Postal code. |
| `CityName` | City or postal area. |
| `CountryCode` | Country code according to ISO 3166-1 alpha-2. |
| `MunicipalityCode` | Optional municipality code. |
| `FloorIdentification` | Optional floor identification. |
| `RoomIdentification` | Optional room identification. |
| `AttentionOf` | Optional attention-of value. |
| `OnBehalfOf` | Optional on-behalf-of value. |
| `CareOf` | Optional care-of value. |

Use either `StreetName` and `BuildingNumber`, or `PostofficeBox`.

## Communication fields

```json
{
  "Channel": "Email",
  "Value": "customer@example.com",
  "Description": "Customer email"
}
```

| Field | Description |
|---|---|
| `Channel` | Communication channel. Common values are `Email`, `Mobile`, and `Phone`. |
| `Value` | Email address or phone number. Phone numbers should include country calling code, for example `+4799988777`. |
| `Description` | Optional description. |

## Existing customer and Account

If the customer and Account already exist and no properties need to be updated, the `Customer` and `Account` objects can be simplified.

```json
{
  "Account": {
    "Guid": "8a46b4b9-bae0-40bc-83dc-0b63eb022fde"
  }
}
```

## Accounting Point

The `AccountingPoint` object identifies the Accounting Point where the contract should apply.

```json
{
  "AccountingPoint": {
    "Identification": "707057500012345678"
  }
}
```

For Norwegian electricity, the Accounting Point identification is typically an 18-digit metering point id.

The Accounting Point must exist before a contract is created on it. Other API methods may be used to create Accounting Points if required.

## Consent identifier

For Norwegian Elhub agreement control, the consent id can be included as an identifier on the Accounting Point section for the contract.

```json
{
  "AccountingPoint": {
    "Identification": "707057500012345678",
    "IdentifiersForContract": [
      {
        "Source": "ConsentId",
        "Identification": "the consent id from Elhub",
        "Description": "optional description"
      }
    ]
  }
}
```

## Multiple Accounting Points

It is possible to create multiple contracts for the same customer and Account with the same Products and start/end date.

Use `AccountingPoints` instead of `AccountingPoint`.

```json
{
  "AccountingPoints": [
    {
      "Identification": "707057500012345678"
    },
    {
      "Identification": "707057500087654321"
    }
  ]
}
```

## Products

The `Products` array defines the products that should be part of the contract.

Products must already exist in UtilityCloud.

```json
{
  "Products": [
    {
      "ProductId": "6d1224116b6f42979815836fb343bb60",
      "ProductName": "Fastpris 1 år",
      "PrimaryProduct": true,
      "StartDate": "2026-06-01T22:00:00Z",
      "EndDate": null,
      "InteractivePrices": [
        {
          "Name": "i:Paaslag",
          "Value": "0.73"
        }
      ]
    }
  ]
}
```

## Product fields

| Field | Description |
|---|---|
| `ProductId` | Identifier of an existing product in UtilityCloud. |
| `ProductName` | Optional product name. |
| `PrimaryProduct` | Indicates whether the product is the primary product. |
| `StartDate` | Date from which the product should apply. Usually the same as the contract `StartDate`. |
| `EndDate` | Optional end date for the product. |
| `InteractivePrices` | Product-specific price values. Required when the product has interactive fields. |

Some products have interactive fields. When a product has interactive fields, the `InteractivePrices` array must include name-value pairs for all required fields.

Values must be specified in the primary currency unit, using period (`.`) as decimal separator.

Use the product endpoint to retrieve available products and interactive fields. Check the product `visible` property before creating a contract with that product.

```http
POST /v1/pm/products
```

## Options

The `Options` object is optional. It controls additional processing of the contract.

```json
{
  "Options": {
    "SkipRequestStartOfSupplyFromMarket": false,
    "SkipRequestAccountingPointCharacteristicsFromMarket": false,
    "SkipRequestAccountingPointMeterValuesFromMarket": false,
    "SkipCustomerConfirmation": true,
    "SkipCustomerCreditCheck": true
  }
}
```

| Field | Description |
|---|---|
| `SkipRequestStartOfSupplyFromMarket` | Set to `true` if no start of supply message should be sent to the market hub. |
| `SkipRequestAccountingPointCharacteristicsFromMarket` | Set to `true` if Accounting Point characteristics should not be requested from the market hub. |
| `SkipRequestAccountingPointMeterValuesFromMarket` | Set to `true` if meter values should not be requested from the market hub. |
| `SkipCustomerConfirmation` | Controls whether customer confirmation is skipped. |
| `SkipCustomerCreditCheck` | Controls whether customer credit check is skipped. |

Default value for most options is `false`.

## Dates

`StartDate` and `EndDate` should be provided as ISO date/time values with timezone.

The contract start date must be midnight local time, represented as an ISO date/time with timezone.

Example:

```json
{
  "StartDate": "2026-06-01T22:00:00Z"
}
```

## Notes

Use a new `RequestId` for each API request. The request id is used for tracing and duplicate request handling.

Do not send `null` or empty strings unless the intention is to clear an existing property value.

If an existing customer or Account is found, submitted values may update the existing resource.

A Contract can contain one primary product and optional add-on products.

Products must already exist before they are used on a Contract.

The Accounting Point must exist before a Contract is created on it.

Contract creation may trigger market communication, customer confirmation, credit check, settlement setup, billing setup, events, or other processing depending on Service Type and tenant configuration.

## Contract type guides

For contracts with specific market or service requirements, see the relevant guide:

- [District heating in Norway](/workflows/create-contract/workflow-create-contract-no-dh)

## Related endpoints

```http
POST /v1/cm/contracts
POST /v1/pm/products
POST /v1/cm/customers/search
POST /v1/cm/customers/phone
POST /v1/cm/search/customer
GET /v1/cm/contract/{guid}
```