Create and manage sign requests, consent orders, text templates, and authorization documents.
Get Sign Request for Signatory
Returns the sign request or consent order for the specified signatory, including the data required to render the signing view.
Access is authorized using the signatory's bearer token.
path Parameters
signRequestGuidThe sign request ID.
signatoryIdThe signatory ID.
Get Sign Request for Signatory › Responses
OK
signRequestGuidsignRequestTypelanguageCodecountryCodetimeZonesignAftersignBeforestatuscreatedAtupdatedAtDownload Sign Request File
Downloads a file associated with the sign request or consent order for the specified signatory.
Access is authorized using the signatory's bearer token.
path Parameters
signRequestGuidThe sign request ID.
signatoryIdThe signatory ID.
fileNameThe file name.
Download Sign Request File › Responses
OK
List Text Templates
Retrieves the text templates available for a tenant.
Use this endpoint to list configured text templates that can be used to generate documents or signing content.
List Text Templates › Responses
OK
nameName of the text template.
mediaTypeMedia type (aka MIME type) of the template, e.g. text/plain, text/html.
documentTitleTitle for the PDF document generated from the template. Also used in PDF filename.
contentTemplateTemplate using Handlebars expressions. Use period (.) for nested objects.
descriptiononlyForProductIdsList of product IDs of products which can use this text template. Empty list is available for all products.
textTemplateGuidcreatedAtupdatedAtCreate Text Template
Creates a text template for a tenant.
Create Text Template › Request Body
nameName of the text template.
mediaTypeMedia type (aka MIME type) of the template, e.g. text/plain, text/html.
documentTitleTitle for the PDF document generated from the template. Also used in PDF filename.
contentTemplateTemplate using Handlebars expressions. Use period (.) for nested objects.
descriptiononlyForProductIdsList of product IDs of products which can use this text template. Empty list is available for all products.
Create Text Template › Responses
OK
nameName of the text template.
mediaTypeMedia type (aka MIME type) of the template, e.g. text/plain, text/html.
documentTitleTitle for the PDF document generated from the template. Also used in PDF filename.
contentTemplateTemplate using Handlebars expressions. Use period (.) for nested objects.
descriptiononlyForProductIdsList of product IDs of products which can use this text template. Empty list is available for all products.
textTemplateGuidcreatedAtupdatedAtGet Text Template
Retrieves a text template by ID.
Returns 404 Not Found if no text template exists with the specified ID.
path Parameters
textTemplateGuidThe unique ID of the text template to retrieve.
Get Text Template › Responses
OK
nameName of the text template.
mediaTypeMedia type (aka MIME type) of the template, e.g. text/plain, text/html.
documentTitleTitle for the PDF document generated from the template. Also used in PDF filename.
contentTemplateTemplate using Handlebars expressions. Use period (.) for nested objects.
descriptiononlyForProductIdsList of product IDs of products which can use this text template. Empty list is available for all products.
textTemplateGuidcreatedAtupdatedAtReplace Text Template
Replaces an existing text template.
Use this endpoint when the complete text template should be updated with a new version of the template definition.
path Parameters
textTemplateGuidThe unique ID of the text template to replace.
Replace Text Template › Request Body
nameName of the text template.
mediaTypeMedia type (aka MIME type) of the template, e.g. text/plain, text/html.
documentTitleTitle for the PDF document generated from the template. Also used in PDF filename.
contentTemplateTemplate using Handlebars expressions. Use period (.) for nested objects.
descriptiononlyForProductIdsList of product IDs of products which can use this text template. Empty list is available for all products.
Replace Text Template › Responses
OK
nameName of the text template.
mediaTypeMedia type (aka MIME type) of the template, e.g. text/plain, text/html.
documentTitleTitle for the PDF document generated from the template. Also used in PDF filename.
contentTemplateTemplate using Handlebars expressions. Use period (.) for nested objects.
descriptiononlyForProductIdsList of product IDs of products which can use this text template. Empty list is available for all products.
textTemplateGuidcreatedAtupdatedAtUpdate Text Template
Partially updates a text template using a JSON Patch request (RFC 6902). The request body is an array of operations (changes to apply), each with type of operation, path to element to update, and the new value. If any operation in the array fails, none of the operations are applied.
Operation (op) can be one of these:
add: adds a property to the object or an element to an array; for an existing property it sets a valueremove: removes a property or an array elementreplace: same as remove followed by add at the same locationtest: returns success status code if the value at the specified path equals the specified value
Path (path) starts with a slash (/) and has slashes between levels. Use zero-based index to specify array elements, e.g. /addresses/0. Use hyphen (-) to add to the end of an array, e.g. /addresses/-.
Value (value) can be any JSON object (string, etc).
See learn.microsoft.com for syntax and examples. More details in RFC 6902.
path Parameters
textTemplateGuidThe unique ID of the text template to update.
Update Text Template › Request Body
pathopfromvalueUpdate Text Template › Responses
OK
nameName of the text template.
mediaTypeMedia type (aka MIME type) of the template, e.g. text/plain, text/html.
documentTitleTitle for the PDF document generated from the template. Also used in PDF filename.
contentTemplateTemplate using Handlebars expressions. Use period (.) for nested objects.
descriptiononlyForProductIdsList of product IDs of products which can use this text template. Empty list is available for all products.
textTemplateGuidcreatedAtupdatedAtList Available Text Templates
Retrieves the text templates available for a product.
Use this endpoint to determine which text templates can be used for a specific product.
Templates that are not restricted to specific products are included in the result and sorted after product-specific templates.
query Parameters
productIdThe unique ID of the product to retrieve available text templates for.
List Available Text Templates › Responses
OK
nameName of the text template.
mediaTypeMedia type (aka MIME type) of the template, e.g. text/plain, text/html.
documentTitleTitle for the PDF document generated from the template. Also used in PDF filename.
contentTemplateTemplate using Handlebars expressions. Use period (.) for nested objects.
descriptiononlyForProductIdsList of product IDs of products which can use this text template. Empty list is available for all products.
textTemplateGuidcreatedAtupdatedAtList Standard Text Templates
Get Standard Text Template
Retrieves a standard text template by key.
Returns 404 Not Found if no standard text template exists with the specified key.
path Parameters
standardTextTemplateKeyGet Standard Text Template › Responses
OK
standardTextTemplateKeynamedescriptionmediaTypedocumentTitlecontentTemplateupdatedAtList Sign Requests
Retrieves sign requests for a tenant.
Results are paged. The first page is 1.
query Parameters
pageSizeThe number of sign requests to return per page. Default page size is 10.
pageNumberThe page number to retrieve. The first page is 1, and the default value is 1.
List Sign Requests › Responses
OK
signRequestGuidsignRequestTypetextTemplateGuidlanguageCodecountryCodetimeZonesignAftersignBeforestatusexternalSignOrderIdexternalStatuscreatedAtupdatedAtGet Sign Request
Retrieves a sign request by ID.
Returns 404 Not Found if no sign request exists with the specified ID.
path Parameters
signRequestGuidThe unique ID of the sign request to retrieve.
Get Sign Request › Responses
OK
signRequestGuidsignRequestTypetextTemplateGuidlanguageCodecountryCodetimeZonesignAftersignBeforestatusexternalSignOrderIdexternalStatuscreatedAtupdatedAtGet Sign Request by Reference
Retrieves a sign request by reference type and reference ID.
Returns 404 Not Found if no sign request exists for the specified reference.
path Parameters
referenceTypeThe referenced resource type. Supported values are Offer and Contract.
referenceIdThe ID of the resource referenced by the sign request.
Get Sign Request by Reference › Responses
OK
signRequestGuidsignRequestTypetextTemplateGuidlanguageCodecountryCodetimeZonesignAftersignBeforestatusexternalSignOrderIdexternalStatuscreatedAtupdatedAtGet Sign Request Summary by Reference
Retrieves a sign request summary by reference type and reference ID.
Use this endpoint when only the key sign request properties are needed, for example in WebOrder flows.
Returns 404 Not Found if no sign request exists for the specified reference.
path Parameters
referenceTypeThe referenced resource type. Supported values are Offer and Contract.
referenceIdThe ID of the referenced offer or contract.
Get Sign Request Summary by Reference › Responses
OK
signRequestGuidThe unique identifier for the sign request.
signUrlThe short URL if available, otherwise the long URL.
signUrlLongThe long URL.
ssoParametersSingle sign-on parameter(s) which can be appended to the query string of SignUrlLong. Based on the JWT token in the request.
Create Sign Request with Files
Creates a sign request with JSON metadata and one or more documents to sign.
Use this endpoint when the documents to be signed are uploaded together with
the sign request. The request must use multipart/form-data.
The multipart form data must contain:
json: A text field containing the sign request JSON.file: One or more file fields containing the documents to sign.
The json field must use the same JSON model as the documented request body
for creating a sign request with attached files.
See POST signrequests/docforattachedfiles
Max size of a single file is ≈ 5 MB, and max total size of all files is ≈ 9 MB.
Note: Swagger UI may not support sending this multipart request correctly. Use Postman or application code when testing this endpoint.
Create Sign Request with Files › Request Body
jsonUse key json of type Text containing JSON. Use Postman or code to send this. Swagger UI doesn't work.
fileUse one or more files all with key file of type File.
Create Sign Request with Files › Responses
OK
signRequestGuidCreate Sign Request with Signed Files
Creates a sign request with JSON metadata and one or more already signed PDF files.
Use this endpoint when the documents have already been signed outside UtilityCloud
and should be registered as signed files. The request must use multipart/form-data.
The multipart form data must contain:
json: A text field containing the sign request JSON.file: One or more file fields containing the signed PDF files.
The json field must use the documented sign request payload model for signed files.
See POST signrequests/docforsignedfiles
Max size of a single file is ≈ 5 MB, and max total size of all files is ≈ 9 MB.
Note: Swagger UI may not support sending this multipart request correctly. Use Postman or application code when testing this endpoint.
Create Sign Request with Signed Files › Request Body
jsonUse key json of type Text containing JSON. Use Postman or code to send this. Swagger UI doesn't work.
fileUse one or more files all with key file of type File.
Create Sign Request with Signed Files › Responses
OK
signRequestGuidCreate Sign Request from Text Templates
Creates a sign request and generates the PDF documents to sign from text templates.
Create Sign Request from Text Templates › Request Body
signRequestTypelanguageCodecountryCodetimeZonetextTemplateGuidsisPersonsignAftersignBeforeCreate Sign Request from Text Templates › Responses
OK
signRequestGuidCancel Sign Request
Cancels a sign request.
Only sign requests with status Unknown, InProgress, or Error can be cancelled.
path Parameters
signRequestGuidThe unique ID of the sign request to cancel.
Cancel Sign Request › Responses
OK
signRequestGuidsignRequestTypetextTemplateGuidlanguageCodecountryCodetimeZonesignAftersignBeforestatusexternalSignOrderIdexternalStatuscreatedAtupdatedAtUpdate Sign Request
Update sign request with the current statuses from Idura (fka Criipto) and retry Elhub errors.
path Parameters
signRequestGuidThe unique ID of the sign request to update.
Update Sign Request › Responses
OK
signRequestGuidsignRequestTypetextTemplateGuidlanguageCodecountryCodetimeZonesignAftersignBeforestatusexternalSignOrderIdexternalStatuscreatedAtupdatedAtRetry Sign Request PDF Generation
Retries PDF generation for a sign request.
Use this endpoint to restart PDF generation when the previous generation attempt failed or did not complete successfully.
path Parameters
signRequestGuidThe unique ID of the sign request to retry PDF generation for.
Retry Sign Request PDF Generation › Responses
OK
signRequestGuidsignRequestTypetextTemplateGuidlanguageCodecountryCodetimeZonesignAftersignBeforestatusexternalSignOrderIdexternalStatuscreatedAtupdatedAtRetry sending Sign Request to Idura
Retries sending the sign request to Idura. Will return BadRequest if the sign request has already been sent to Idura if PDFs have not been generated yet, if we have no Elhub PDF, or .
path Parameters
signRequestGuidThe unique ID of the sign request to retry Idura for.
Retry sending Sign Request to Idura › Responses
OK
signRequestGuidsignRequestTypetextTemplateGuidlanguageCodecountryCodetimeZonesignAftersignBeforestatusexternalSignOrderIdexternalStatuscreatedAtupdatedAtUpload files to a Sign Request
Upload PDF files to be associated with an existing sign request.
Use this endpoint when the documents have already been signed outside UtilityCloud
and should be registered as signed files. The request must use multipart/form-data.
The multipart form data must contain:
file: One or more file fields containing the signed PDF files.
Max size of a single file is ≈ 5 MB, and max total size of all files is ≈ 9 MB.
Note: Swagger UI may not support sending this multipart request correctly. Use Postman or application code when testing this endpoint.
path Parameters
signRequestGuidThe unique ID of the sign request.
Upload files to a Sign Request › Request Body
fileUse one or more files all with key file of type File.
Upload files to a Sign Request › Responses
OK
Resend Sign Request Communication
Resends email and/or SMS communication for a sign request.
Use this endpoint when a recipient needs to receive the signing link again.
If the sign request has multiple signers, the request must include
SsnFirstSixDigits to identify which signer should receive the communication.
path Parameters
signRequestGuidThe unique ID of the sign request.
Resend Sign Request Communication › Request Body
communicationStagemailAddressmobileNumberssnFirstSixDigitsResend Sign Request Communication › Responses
OK
Get Offer Merge Data
Retrieves the JSON merge data used to generate offer documents.
Use this endpoint when a client needs the data model used for rendering offer PDFs or previewing offer document templates.
Use the empty GUID 00000000-0000-0000-0000-000000000000 to retrieve fake
preview data instead of data for an existing offer.
path Parameters
offerGuidThe unique ID of the offer, or the empty GUID to retrieve fake preview data.
query Parameters
fakeApsCountThe number of fake metering points to include when retrieving preview data.
previewProductIdThe product ID to use when retrieving preview data.
Get Offer Merge Data › Responses
OK
List Offer Merge Fields
Retrieves the available merge fields for offer document templates.
Use this endpoint to show which fields can be used when rendering offer texts or offer documents. Field names and descriptions are returned in the requested language when available.
If the language code is omitted, unknown, or not supported, English is used.
query Parameters
languageCode^[a-z]{2}$The ISO 639-1 language code, using two lowercase letters, for example en, no, fi, or sv.
List Offer Merge Fields › Responses
OK
codenamedescriptionGenerate Text from Template
Merges a template with JSON data using Handlebars expressions. Can also be used to make sure the expressions in the template are valid. Returns 200-OK if the syntax is correct.
The use of HTML tags in property values in jsonData is not supported.
For more information on Handlebars expressions see its language guide.
Generate Text from Template › Request Body
templateTemplate using Handlebars expressions. Use period (.) for nested objects.
dataOptional. Data as a JSON object. Use as an alternative to JsonData.
jsonDataOptional. Data as a JSON object serialized to string. Only used if Data is null.
contentTypeOptional. MIME type of the response, e.g. text/html. Will be returned as a Content-Type HTTP header. Default is text/plain.
Generate Text from Template › Responses
OK
Generate PDF from Template
Generates a PDF document from an HTML template merged with JSON data using Handlebars expressions.
The use of HTML tags in property values in jsonData is not supported.
If setting headerHtmlTemplate and/or footerHtmlTemplate, also set pdfOptions.margins.top and/or pdfOptions.margins.bottom.
Also set a font-size for your header/footer (e.g. <div style="font-size:9px;"> ... </div>).
For more information on Handlebars expressions see its language guide.
We're using Chrome (headless) which uses Skia to create PDFs. If the HTML looks good in Chrome, the PDF should look good too.
Use CSS page-break to split the content into several pages (details).
Use PdfTitle or a HTML title tag to set the PDF's title property. No other PDF properties can be set.
The Content-Type HTTP header of the response is application/pdf.
Generate PDF from Template › Request Body
contentHtmlTemplateHTML template for the content using Handlebars expressions. Use period (.) for nested objects.
The HTML will be prefixed with <html><head></head><body> and suffixed with </body></html> if either part is missing.
pdfTitleTitle of the generated PDF. Will be used in the HTML <title> tag, if title is not set in the ContentHtmlTemplate.
dataOptional. Data as a JSON object. Use as an alternative to JsonData.
jsonDataOptional. Data as a JSON object serialized to string. Only used if Data is null.
filenameOptional. Filename of the generated PDF. Default is no filename (null). Will be returned in a Content-Disposition HTTP header.
headerHtmlTemplateHTML template for the page header using Handlebars expressions.
Remember to set pdfOptions.margins.top.
Use HTML tags with these CSS classes to get special values:
date - formatted print date,
title - document title,
url - document location,
pageNumber - current page number,
totalPages - total pages in the document.
More details on setting header/footer.
footerHtmlTemplateHTML template for the page footer using Handlebars expressions.
Remember to set pdfOptions.margins.bottom.
Similar to the template for header. See it for details.
Generate PDF from Template › Responses
OK
Get Template Merge Information
Returns information about how to use text templates for merging data, including the available merge fields.
When the language code is omitted, unknown, or not supported, English is used.
query Parameters
languageCode^[a-z]{2}$Language code must be two lowercase letters (a-z) used in ISO 639-1. If language code is unknown or we don't have a translation, "en" (english) is used.
Get Template Merge Information › Responses
OK
headingcontentList Authorization Documents
Retrieves the authorization documents available for a tenant. Use this endpoint to get authorization documents that can be used in signing or consent workflows.
Paging is not currently supported for this operation.
List Authorization Documents › Responses
OK
iddocumentTypestatuscreatedAtupdatedAtvalidTorequestedFromNamerequestedForMeteringPointIdrequestedForMeteringPointAddressbalanceSupplierNamebalanceSupplierContractNamemoveInDateUse a date in format "yyyy-MM-dd"
languageCreate Authorization Document
Creates an authorization document for a person and metering point.
Use this endpoint when a signing or consent workflow requires an authorization document for a specific person and metering point. The request body contains the person information, metering point data, language code, and time zone used to create the document.
Create Authorization Document › Request Body
personNamepersonSsnlanguageCodetimeZoneTime zone identifier, e.g. Europe/Oslo, according to tz/IANA time zone database (https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), e.g. Europe/Oslo (which is +01:00 or +02:00).
documentTypeproductNamemeteringPointIdmeteringPointAddressstartDateTimeIn ISO 8601 format. For example: "2024-06-30T12:34:56Z" or "2024-06-30T14:34:56+02:00". Note: will be converted to a date in the specified time zone before sending to Elhub.
Create Authorization Document › Responses
OK
iddocumentTypestatuscreatedAtupdatedAtvalidTorequestedFromNamerequestedForMeteringPointIdrequestedForMeteringPointAddressbalanceSupplierNamebalanceSupplierContractNamemoveInDateUse a date in format "yyyy-MM-dd"
languageGet Authorization Document
Retrieves an authorization document by ID. Use this endpoint to get the details of a specific authorization document for a tenant. Returns a 404 Not Found response if the specified authorization document does not exist for the given tenant.
path Parameters
authDocIdThe unique identifier of the authorization document to retrieve.
Get Authorization Document › Responses
OK
iddocumentTypestatuscreatedAtupdatedAtvalidTorequestedFromNamerequestedForMeteringPointIdrequestedForMeteringPointAddressbalanceSupplierNamebalanceSupplierContractNamemoveInDateUse a date in format "yyyy-MM-dd"
languageReplace Authorization Document PDF
Replaces the PDF file for an existing authorization document. Only a single file upload is supported. The maximum allowed file size is approximately 500 KB. If more than one file is provided, the request will be rejected.
path Parameters
authDocIdThe unique identifier of the authorization document to update.
Replace Authorization Document PDF › Request Body
fileThe collection of files uploaded with the request. Must contain exactly one PDF file to be used as the updated document.
Replace Authorization Document PDF › Responses
OK
Get Authorization Document PDF
Retrieves an authorization document as a PDF file. Use this endpoint to download the PDF representation of a specific authorization document.
Note: If the authorization document does not exist, Elhub return 406 Not Acceptable.
path Parameters
authDocIdThe unique identifier of the authorization document to retrieve. This value is required and must be provided in the route.
Get Authorization Document PDF › Responses
OK
Get Market Party
Retrieves market party information by Global Location Number (GLN).
Returns 404 Not Found if no matching market party exists.
query Parameters
glnThe Global Location Number (GLN) of the market party to look up. Cannot be null.
Get Market Party › Responses
OK
glnnameGet Consent Order
Returns the consent order for the specified signatory.
Access is authorized using the signatory key. When the consent order has already been accepted by all signatories, the request is rejected with 451 unless view mode is used.
path Parameters
signRequestGuidThe sign request ID.
signatoryIdThe signatory ID.
query Parameters
keyThe access key calculated for the signatory.
modeThe retrieval mode. Use view mode to retrieve an already accepted consent order.
Get Consent Order › Responses
OK
signRequestGuidsignRequestTypeisPersonlanguageCodecountryCodetimeZonesignAftersignBeforepersonNamesToSigndocumentFileNamesToSignDownload Consent Order File
Downloads a file associated with the consent order for the specified signatory.
Access is authorized using the signatory key.
path Parameters
signRequestGuidThe sign request ID.
signatoryIdThe signatory ID.
fileNameThe file name.
query Parameters
keyThe access key calculated for the signatory.
modeThe retrieval mode. Use view mode to access a consent order that has already been accepted.
Download Consent Order File › Responses
OK
Check Consent Order Access
Validates signatory access to a consent order and returns the resulting status without returning the consent order or any file content.
path Parameters
signRequestGuidThe sign request ID.
signatoryIdThe signatory ID.
query Parameters
keyThe access key calculated for the signatory.
Check Consent Order Access › Responses
OK
Update Consent Order Status to Opened
Records that the signatory has opened the consent order.
The status is updated only while the consent order is in progress.
path Parameters
signRequestGuidThe sign request ID.
signatoryIdThe signatory ID.
query Parameters
keyThe access key calculated for the signatory.
Update Consent Order Status to Opened › Responses
OK
Update Consent Order Status to Accepted
Records that the signatory has accepted the consent order.
The status is updated only while the consent order is in progress. Authentication details are captured from the bearer token when present.
path Parameters
signRequestGuidThe sign request ID.
signatoryIdThe signatory ID.
query Parameters
keyThe access key calculated for the signatory.
Update Consent Order Status to Accepted › Responses
OK
Update Consent Order Status to Rejected
Records that the signatory has rejected the consent order, including the rejection reason.
The status is updated only while the consent order is in progress.
path Parameters
signRequestGuidThe sign request ID.
signatoryIdThe signatory ID.
query Parameters
keyThe access key calculated for the signatory.
Update Consent Order Status to Rejected › Responses
OK
Update Consent Order Status to Failed
path Parameters
signRequestGuidThe sign request ID.
signatoryIdThe signatory ID.
query Parameters
keyThe access key calculated for the signatory.
Update Consent Order Status to Failed › Responses
OK