Copy page

Common workflows

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

Code
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:

Code
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.

Code
{
  "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

Code
{
  "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

Code
{
  "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

Code
{
  "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.

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

Accounting Point

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

Code
{
  "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.

Code
{
  "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.

Code
{
  "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.

Code
{
  "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.

Code
POST /v1/pm/products

Options

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

Code
{
  "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:

Code
{
  "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

Related endpoints

Code
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}