This documentation will describe the verious endpoints available to interact with your wholesale agreement via the Vertical Integrate API.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"47421989","collectionId":"79fde42b-3b2d-42ac-8f41-77391d512e85","publishedId":"2sB3WvKwyo","public":true,"customColor":{"top-bar":"1c1c3b","right-sidebar":"1c1c3b","highlight":"6b38e5"},"publishDate":"2025-11-12T14:39:49.000Z"},"item":[{"name":"Auth","item":[],"id":"86b397e9-986f-469d-b77b-3ec9643b495f","description":"The Vertical Integrate API is a RESTful API which requires an API key and an API secret, issued by Vertical, to access.
\nGET requests contain no body payload and so only require the API key to be passed in the API-KEY header
\nRequests which send a payload in the body require, in addition to the API key passed in the headers, an HMAC hash of the body payload to be sent in another header, API-HASH, using the issued API secret.
\nExample in PHP, where $payload is your JSON body:
$hash = hash_hmac(\"sha512\", $payload, $secret);\n curl_setopt($ch, CURLOPT_HTTPHEADER, array(\n \"API-KEY: {$key}\",\n \"API-HASH: {$hash}\"\n ));\n\nTo use this postman collections the below environmental variables should be set:
\nAll values in single {} should be replaced with the appropriate value.
\n","_postman_id":"86b397e9-986f-469d-b77b-3ec9643b495f"},{"name":"Quote","item":[{"name":"Get Quote","event":[{"listen":"prerequest","script":{"id":"371623b3-734b-42e8-9e64-4758804e2c12","exec":[""],"type":"text/javascript","packages":{}}}],"id":"78d829cb-2e08-457b-9476-232438183a0d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"API-KEY","value":"{{API_key}}","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":"{{base_url}}/quote?address={address}&town={town}&postcode={postcode}&capacity={capacity}&start_date={start_date}&end_date={end_date}&udprn={udprn}&uprn={uprn}&electricity={electricity}&gas={gas}&broadband={broadband}&water={water}&tvl={tvl}&is_unlimited={is_unlimited}","urlObject":{"path":["quote"],"host":["{{base_url}}"],"query":[{"description":{"content":"The properies address lines, excluding the town and postcode
\n","type":"text/plain"},"key":"address","value":"{address}"},{"description":{"content":"The town of the property.
\n","type":"text/plain"},"key":"town","value":"{town}"},{"description":{"content":"The properties postcode. The format must include a space between the outward and inward code.
\n","type":"text/plain"},"key":"postcode","value":"{postcode}"},{"description":{"content":"The number of people who will be living at the property.
\n","type":"text/plain"},"key":"capacity","value":"{capacity}"},{"description":{"content":"The date the contract will start in YYYY-MM-DD format.
\n","type":"text/plain"},"key":"start_date","value":"{start_date}"},{"description":{"content":"The contract end date. Must be 10 months or more after the start date. Format is YYYY-MM-DD.
\n","type":"text/plain"},"key":"end_date","value":"{end_date}"},{"description":{"content":"The unique delivery point reference number.
\n","type":"text/plain"},"key":"udprn","value":"{udprn}"},{"description":{"content":"The unique property reference number.
\n","type":"text/plain"},"key":"uprn","value":"{uprn}"},{"description":{"content":"Use 1 to include the service in the quote. Otherwise, 0.
\n","type":"text/plain"},"key":"electricity","value":"{electricity}"},{"description":{"content":"Use 1 to include the service in the quote. Otherwise, 0.
\n","type":"text/plain"},"key":"gas","value":"{gas}"},{"description":{"content":"Use 1 to include the service in the quote. Otherwise, 0.
\n","type":"text/plain"},"key":"broadband","value":"{broadband}"},{"description":{"content":"Use 1 to include the service in the quote. Otherwise, 0.
\n","type":"text/plain"},"key":"water","value":"{water}"},{"description":{"content":"Use 1 to include the service in the quote. Otherwise, 0.
\n","type":"text/plain"},"key":"tvl","value":"{tvl}"},{"description":{"content":"Is for unlimited agreement
\n","type":"text/plain"},"key":"is_unlimited","value":"{is_unlimited}"}],"variable":[]}},"response":[{"id":"16a43766-cb37-4af5-bf3b-01b92288970d","name":"200 Success","originalRequest":{"method":"GET","header":[{"key":"API-KEY","value":"•••••••","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":{"raw":"https://api.test.durham.cloud/wholesale/quote?address=&town=&postcode&capacity=&start_date=&end_date=&udprn=&uprn=&electricity=1&gas=1&broadband=1&water=1&tvl=0","protocol":"https","host":["api","test","durham","cloud"],"path":["wholesale","quote"],"query":[{"key":"address","value":"","description":"The properies address lines, excluding the town and postcode **Required**"},{"key":"town","value":"","description":"The town of the property. **Required**"},{"key":"postcode","value":null,"description":"The properties postcode. The format must include a space between the outward and inward code."},{"key":"capacity","value":"","description":"The number of people who will be living at the property. **Required**"},{"key":"start_date","value":"","description":"The date the contract will start in YYYY-MM-DD format. **Required**"},{"key":"end_date","value":"","description":"The contract end date. Must be 10 months or more after the start date. Format is YYYY-MM-DD. **Required**"},{"key":"udprn","value":"","description":"The unique delivery point reference number."},{"key":"uprn","value":"","description":"The unique property reference number."},{"key":"electricity","value":"1","description":"Use 1 to include the service in the quote. Otherwise, 0. **Required**"},{"key":"gas","value":"1","description":"Use 1 to include the service in the quote. Otherwise, 0. **Required**"},{"key":"broadband","value":"1","description":"Use 1 to include the service in the quote. Otherwise, 0. **Required**"},{"key":"water","value":"1","description":"Use 1 to include the service in the quote. Otherwise, 0. **Required**"},{"key":"tvl","value":"0","description":"Use 1 to include the service in the quote. Otherwise, 0. (TV Licence) **Required**"},{"key":"is_unlimited","value":"0","description":"Is for unlimited agreement","type":"text","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Mon, 11 Aug 2025 13:19:10 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Cache-Control","value":"private, must-revalidate"},{"key":"pragma","value":"no-cache"},{"key":"expires","value":"-1"},{"key":"X-RateLimit-Limit","value":"300"},{"key":"X-RateLimit-Remaining","value":"298"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Encoding","value":"gzip"}],"cookie":[],"responseTime":null,"body":"{\n \"electricity\":\t{\n//Price structure for an energy service quote. Service will only be displayed if selected on request.\n\n \"is_available\": \"Use this endpoint to generate a quote for a contract based on the information provided.
\n","_postman_id":"9f5a8732-5366-40c4-86dc-e18d87bce366"},{"name":"Contract","item":[{"name":"Create Contract","event":[{"listen":"prerequest","script":{"id":"bc5d26a7-11ff-4b24-ba89-b57d0c0319c0","exec":["// get secret","var secret = pm.environment.get(\"secret\");","// get request body","var req = request.data","var requestBody = pm.variables.replaceIn(pm.request.body.raw);","","// create HMAC SHA512 hash request body and secret","var hashHmacSHA512 = CryptoJS.enc.Hex.stringify(CryptoJS.HmacSHA512(requestBody, secret));","// add headers to request","pm.environment.set(\"API-HASH\", hashHmacSHA512);"],"type":"text/javascript","packages":{}}}],"id":"c76b3956-0ceb-4ad2-af4d-ac824b4e38ab","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"},{"key":"API-KEY","value":"{{API_key}}","type":"text"},{"key":"API-HASH","value":"{API-HASH}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"address\": \"string\", //The properties address lines, excluding the town and postcode.\n \n \"town\": \"sting\", //The town of the property.\n \n \"postcode\": \"string\", //The properties postcode. The format must include a space between the outward and inward code.\n \n \"capacity\": 2, //The number of people that will be living at the property. (Min: 1, Max: 12)\n \n \"start_date\": \"string\", //The date the contract will be started from in YYYY-MM-DD format.\n \n \"end_date\": \"string\", //The end date for the contract. Date must be 10 months ahead of start_date and format YYYY-MM-DD.\n \n \"udprn\": \"sting\", //8 char unique delivery point reference number.\n \n \"uprn\": \"string\", //12 char unique property reference number.\n \n \"electricity\": true, //Wholesale contracts must have electricity. Therefore, this should be true.\n \n \"gas\": true, //True if the contract should have gas. Otherwise, false\n \n \"water\": true, //True if the contract should have water. Otherwise, false.\n \n \"tvl\": false, //True if the contract should have TV licence. Otherwise, false.\n \n \"broadband\": true, //True if the contract should have broadband. Otherwise, false.\n \n \"is_unlimited\": true //Is for unlimited agreement\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/contract","description":"Add a new contract to your existing wholesale agreement.
\n","urlObject":{"path":["contract"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"1db07185-4e28-459f-95ca-32c0cb76faca","name":"200 Success","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"},{"key":"API-KEY","value":"•••••••","type":"text"},{"key":"API-HASH","value":"{API-HASH}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"address\": \"string\",\n \"town\": \"sting\",\n \"postcode\": \"string\",\n \"capacity\": 2,\n \"start_date\": \"string\",\n \"end_date\": \"string\",\n \"udprn\": \"sting\",\n \"uprn\": \"string\",\n \"electricity\": true,\n \"gas\": true,\n \"water\": true,\n \"tvl\": false,\n \"broadband\": true,\n \"is_unlimited\": true\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/contract"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"reference\": \"Retrive information of an existing contract assosiated with your wholesale agreement.
\nPath Parameters:
\nThe contract reference can be obtained via the 'Properties' tab location in your TSEG portal
\n","urlObject":{"path":["contracts","{contract_reference}"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"215793ef-bc35-4bf5-bd19-30de5f0b28a8","name":"200 Success","originalRequest":{"method":"GET","header":[{"key":"API-KEY","value":"•••••••","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"url":"{{base_url}}/contracts/{contract_reference}"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"reference\": \"Use this endpoint to update the end date of a contract
\nPath Parameters:
\nThe contract reference can be obtained via the 'Properties' tab location in your TSEG portal.
\n","urlObject":{"path":["contracts","{contract_reference}","dates","end"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"4ea89f93-c02e-4705-b11d-7f77e3982dd2","name":"200 Success","originalRequest":{"method":"PATCH","header":[{"key":"API-KEY","value":"•••••••","type":"text"},{"key":"Accept","value":"application/json","type":"text"},{"key":"API-HASH","value":"{API-HASH}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"date\": \"string\"\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/contracts/{contract_reference}/dates/end"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 12 Aug 2025 08:11:55 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Cache-Control","value":"private, must-revalidate"},{"key":"pragma","value":"no-cache"},{"key":"expires","value":"-1"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Encoding","value":"gzip"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true\n //Truthy boolean indicating successful operation.\n}"},{"id":"f2bce951-4193-4fa0-98ab-98b6e9b25e7f","name":"400 Bad Request","originalRequest":{"method":"PATCH","header":[{"key":"API-KEY","value":"•••••••","type":"text"},{"key":"Accept","value":"application/json","type":"text"},{"key":"API-HASH","value":"{API-HASH}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"date\": \"2026/09/01\"\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/contracts/{contract_reference}/dates/end"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 12 Aug 2025 08:12:48 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx"},{"key":"Cache-Control","value":"private, must-revalidate"},{"key":"pragma","value":"no-cache"},{"key":"expires","value":"-1"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Use this endpont to provide the letting agent details of a contract realted to your wholesale agreement.
\nPath Parameters:
\nThe contract reference can be obtained via the 'Properties' tab location in your TSEG portal.
\n","urlObject":{"path":["contracts","{contract_reference}","letting-agents"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"a4f63528-7197-47c2-bc8a-bf53610f7093","name":"200 Success","originalRequest":{"method":"POST","header":[{"key":"API-KEY","value":"•••••••","type":"text"},{"key":"API-HASH","value":"{API-HASH}","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"string\",\n \"email\": \"string\",\n \"telephone\": \"string\",\n \"responsible_from\": \"string\"\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/contracts/{contract_reference}/letting-agents"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 12 Aug 2025 12:34:10 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Cache-Control","value":"private, must-revalidate"},{"key":"pragma","value":"no-cache"},{"key":"expires","value":"-1"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Encoding","value":"gzip"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true\n //Truthy boolean indicating successful operation.\n}"},{"id":"1077faa3-0f33-4791-a685-196ef5d9b791","name":"400 Bad Request","originalRequest":{"method":"POST","header":[{"key":"API-KEY","value":"•••••••","type":"text"},{"key":"API-HASH","value":"{API-HASH}","type":"text"},{"key":"Accept","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"name\": \"string\",\n \"email\": \"string\",\n \"telephone\": \"string\"\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/contracts/{contract_reference}/letting-agents"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 12 Aug 2025 12:33:19 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx"},{"key":"Cache-Control","value":"private, must-revalidate"},{"key":"pragma","value":"no-cache"},{"key":"expires","value":"-1"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Use this endpoint to proved details of a person living in the property this contract relates to.
\nPath Parameters:
\nThe contract reference can be obtained via the 'Properties' tab location in your TSEG portal.
\n","urlObject":{"path":["contracts","{contract_reference}","occupants"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"35052beb-59d1-4170-8094-b0c847728fc5","name":"200 Success","originalRequest":{"method":"POST","header":[{"key":"API-KEY","value":"•••••••","type":"text"},{"key":"Accept","value":"application/json","type":"text"},{"key":"API-HASH","value":"{API-HASH}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"firstname\": \"string\",\n \"lastname\": \"string\",\n \"email\": \"string\",\n \"mobile\": \"string\",\n \"date_of_birth\": \"string\",\n \"start_date\": \"string\",\n \"end_date\": \"string\"\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/contracts/{contract_reference}/occupants"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 12 Aug 2025 12:54:14 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Vary","value":"Accept-Encoding"},{"key":"Cache-Control","value":"private, must-revalidate"},{"key":"pragma","value":"no-cache"},{"key":"expires","value":"-1"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"58"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Content-Encoding","value":"gzip"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true\n //Truthy boolean indicating successful operation.\n}"},{"id":"7daa617e-aca7-4d62-80d4-072495da980e","name":"400 Bad Request","originalRequest":{"method":"POST","header":[{"key":"API-KEY","value":"•••••••","type":"text"},{"key":"Accept","value":"application/json","type":"text"},{"key":"API-HASH","value":"{API-HASH}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"firstname\": \"string\",\n \"lastname\": \"string\",\n \"email\": \"string\",\n \"mobile\": \"string\",\n \"date_of_birth\": \"string\",\n \"start_date\": \"string\",\n \"end_date\": \"string\"\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/contracts/{contract_reference}/occupants"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Tue, 12 Aug 2025 12:57:46 GMT"},{"key":"Content-Type","value":"application/json","description":"","type":"text"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx"},{"key":"Cache-Control","value":"private, must-revalidate"},{"key":"pragma","value":"no-cache"},{"key":"expires","value":"-1"},{"key":"X-RateLimit-Limit","value":"60"},{"key":"X-RateLimit-Remaining","value":"59"},{"key":"Access-Control-Allow-Origin","value":"*"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Use this endpoint to reconcile a contract, this will calculate and return usage data for energy services.
\nPath Parameters:
\nThe contract reference can be obtained via the 'Properties' tab location in your TSEG portal.
\n","urlObject":{"path":["contracts","{reference}","reconciliation"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"9378addc-3aed-40fe-b780-9ccef09e0265","name":"200 Success","originalRequest":{"method":"POST","header":[{"key":"API-KEY","value":"•••••••","type":"text"},{"key":"Accept","value":"application/json","type":"text"},{"key":"API-HASH","value":"{API-HASH}","type":"text"}],"body":{"mode":"raw","raw":"{\n \"date\": \"string\" //The date to reconcile up to in YYYY-MM-DD format.\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/contracts/{reference}/reconciliation"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"[\n//The services included in the reconciliation.\n {\n \"name\": \"Use this endpoint to submit a meter reading for a particular contract and service.
\nPath Parameters:
\n