The Affiliate API provides all the tools you need to programmatically:
\nTo get in touch with our development team, please email partnerships-dev@oneutilitybill.co
Using the postcode and bed-size of the property you submit to us, we bundle together gas, electric, water and broadband bills into\none simple monthly payment. As many tenants in the student market split the bills and rent properties on a per person, per week basis,\nwe provide all pricing information on a per person per week, per person per month, as well as a total per month basis.
\nQuotes are based on:
\nAll quotes are representative. The services can be changed by the tenant once they engage with us and create a personalised\nquote.
\nCreate a Quote, (POST /quotes) by supplying:
postcode (of the property the quote is for)bed_sizetenancy_start_dateCreate a Lead, (POST /leads) by supplying:
address_line_1, city and postcode)first_name, last_name, email_address, phone_number)The following may also be supplied, but are not required:
\nquote_id (this is obtained by generating a quote, as detailed above, before submitting the lead. The response will contain a quote_id)tenancy_start_date (this may be the proposed move in date)metadata (this is an array of key-value pairs of additional information about the lead. Allowed keys are enquiry_id, lead_source, original_source_agent, is_homebuyer)The inclusion of this additional information will help us to provide an improved service to prospective tenants.
\nWe have the following two environments:
\nThe sandbox environment is located at https://partnerships-sandbox.oneutilitybill.co\nand the base URL for this is https://partnerships-sandbox.oneutilitybill.co/api/v1
\nThe sandbox environment is a mirror of the production environment, with the following differences:
\nHowever, it would still be prudent not to use any real customer data in this sandbox environment.
\nThe production environment is located at https://partnerships-api.oneutilitybill.co\nand the base URL for this is https://partnerships-api.oneutilitybill.co/api/v1
\nAll production data is completely separate to sandbox data, anything done on the production environment will not affect the sandbox\nenvironment and vice versa.
\nAn up-to-date OpenAPI 3.0 specification file can be found here, ready to be consumed by your own OpenAPI tooling.
\nTo get started using the Affiliate API please get in touch with Amie Henzell at amie.henzell@oneutilitybill.co who will take you through the onboarding process.
When it is time for you to integrate with our Sandbox Environment, our development team will help get you started. We can always be reached at partnerships-dev@oneutilitybill.co.
We will create for you:
\nOnce we are both happy with your integration in the sandbox environment, we will create the necessary production OAuth 2.0 credentials.
\nThe Affiliate API uses the standard OAuth 2.0 protocol for authentication and authorization.
\nIt supports the Client Credentials grant type.\nYou use a Client ID & Client Secret to acquire a short-lived Access Token.
\nWe will provide you with the Client ID & Client Secret, which you should store securely.\nWe only support server to server API communication, you should not store these in the browser or make calls directly to the Affiliate API from a browser.
\nWe recommend using popular maintained OAuth 2.0 libraries to help you complete the authentication process.
\nThe Affiliate API currently supports the following scopes to define what access your Access Token will be granted:
\nleads - Read & write access to the Leads resourcequotes - Read & write access to the Quotes resourceTo perform authentication, issue a POST request as shown below to the /oauth/token endpoint
POST https://partnerships-sandbox.oneutilitybill.co/oauth/token HTTP/1.1\nContent-Type: application/x-www-form-urlencoded\n...\ngrant_type=client_credentials\n&client_id=xxxxxxxxxxxxxxxxxx\n&client_secret=xxxxxxxxxxxxxx\n&scope=leads+quotes\nHere's each request body parameter explained (remember to URL encode them):
\ngrant_type=client_credentials - This tells the token endpoint it is using the Client Credentials flowclient_id - This is your client_idclient_secret - This is your client_secretscope - This is a space separated list of scopes you are requesting (see the Scopes section above)If everything checks out, you will receive a response like the following:
\nHTTP/1.1 200 OK\nContent-Type: application/json\nCache-Control: no-store\nPragma: no-cache\n...\n{\n\"access_token\":\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\n\"token_type\":\"Bearer\",\n\"expires_in\":3600\n}\nAccess Tokens issued by the Affiliate API are valid for 3600 seconds (1 hour).
\nYou will not receive a Refresh Token as part of this response because the Client Credentials grant type does not use Refresh Tokens.
\nOnce your Access Token expires, you will begin to receive 401 Unauthorized errors from your API requests.
To acquire a new Access Token, simply repeat the same call described above to the /oauth/token endpoint to acquire a new Access Token.
Acquiring a new Access Token does not revoke previously issued Access Tokens.
\nWhen you have an access token, you can use it in the request's HTTP header in the format Authorization: Bearer <access_token>, for example: Authorization: Bearer xxxxxxxxxxxxxxxxxxx
All errors returned by the API follow the same structure. We do not list every possible error response for each endpoint.\nInstead, the common error responses are listed below. Fields which will always be present will be message and meta\ncontaining at least one field named request_id.
This error is returned when the request body you have provided contains validation errors.\nIf there are multiple validation errors, an errors object will be returned and keyed by the violating field, and it's value\nbeing a string array of errors relating to that field.
\n{\n \"message\": \"The postcode must be at least 5 characters. (and 3 more errors)\",\n \"errors\": {\n \"postcode\": [\n \"The postcode must be at least 5 characters.\",\n \"Postcode is malformed.\",\n \"Postcode is not within England, Scotland or Wales.\"\n ],\n \"bed_size\": [\n \"The bed size must be at least 1.\"\n ]\n },\n \"meta\": {\n \"request_id\": \"c36460cbd8f5ed91198066a9e870f0c5dfb11e3b\"\n }\n}\nThis error is returned when the OAuth 2.0 authorization credentials provided are invalid. This may be due to no\ncredentials being provided, invalid credentials, the wrong header being used, or an invalid / expired access token.
\n{\n \"message\": \"Unauthenticated.\",\n \"meta\": {\n \"request_id\": \"61da55be459854e09e8e4dad0574af85fb089239\"\n }\n}\nThe Affiliate API features rate limiting to ensure a quality experience for all consumers of the API.
\nThe rate limits described below apply to you as a consumer (as identified by a Client ID / Secret).
\nTo allow you to more easily encounter and test rate limits when building your integration, we have set the limits to a lower value.
\nThey are currently: 25 requests per 10 seconds.
\nThese are subject to change.
\nFor production, we'll never plan to decrease these limits but they could be increased in the future.
\nThey are currently: 50 requests per 10 seconds.
\nThese are subject to change.
\nThe following headers are present on every API response:
\nX-RateLimit-Limit: This is an integer representing the total limit for the current timeframeX-RateLimit-Remaining: This is an integer representing how many requests you have left for the current timeframeFor example, after making 3 requests in a row on the Sandbox environment you would see:
\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 57\nOnce you hit the rate limit you will receive a 429 Too Many Requests error like the following:
\nHTTP/1.1 429 Too Many Requests\nContent-Type: application/json\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 5\nX-RateLimit-Reset: 1665523508\n...\n{\n\"message\": \"Too Many Attempts.\"\n}\nTwo new headers are included in 429 error responses:
\nRetry-After: This is an integer representing the total number of seconds you should wait before making another requestX-RateLimit-Reset: This is an integer representing the Unix time in UTC when the rate limit will reset, and you can make another requestWe handle both Dates & Timestamps consistently across all of our requests and responses.
\nDates are accepted & provided in Y-m-d format. For example, 2020-05-02.
Timestamps are returned in ISO8601 Zulu Time format, unless stated otherwise. For example, 2020-05-02T09:52:36Z.
We use API wide versioning, specified in the URL. The version number is specified in the base URL, following /api/ and preceding the resource name.
A breaking change refers to any change that would require you to update your application in order to continue working with the Affiliate API as originally intended.
\nWe consider the following to be breaking changes:
\nIf we are intending to make a breaking change, we will communicate this ahead of time to ensure you are able to make the changes in your integration.
\nWe may from time to time make additive changes to our API without incrementing the version number.
\nWe may add new resources and fields to an existing version of the API, and these will not be considered breaking changes. Our API documentation\nexplaining the purpose of the changes will be updated.
\nAs such, you should design your integration to be flexible enough to not break when new fields are added to resources.
\nFor all of our resource IDs, we use UUIDs following the UUID version 7 format.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"API Features","slug":"api-features"}],"owner":"12606501","collectionId":"e489efaa-b898-4a6a-a38d-055c34e13f19","publishedId":"2s8Z76wUiZ","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"3D3D3D","highlight":"FE963D"},"publishDate":"2023-02-02T12:51:11.000Z"},"item":[{"name":"leads","item":[{"name":"leads.store","id":"794e25f7-a7f1-4374-a765-2789b3639e21","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\r\n \"property\": {\r\n \"address_line_1\": \"5 Media Exchange\",\r\n \"city\": \"Newcastle upon Tyne\",\r\n \"postcode\": \"NE1 2QB\",\r\n \"address_line_2\": \"Coquet Street\",\r\n \"county\": \"Tyne and Wear\",\r\n \"uprn\": \"100110971828\",\r\n \"umprn\": \"12345678\",\r\n \"udprn\": \"12345678\"\r\n },\r\n \"contact\": {\r\n \"first_name\": \"John\",\r\n \"last_name\": \"Smith\",\r\n \"email_address\": \"john.smith@oneutilitybill.co\",\r\n \"phone_number\": \"07700964836\",\r\n \"country_code\": \"GB\"\r\n },\r\n \"quote_id\": \"01838daa-eb24-7c54-bac5-ca4eedab22f3\",\r\n \"tenancy_start_date\": \"2022-09-30\",\r\n \"metadata\": [\r\n {\r\n \"meta_key\": \"enquiry_id\",\r\n \"meta_value\": \"123\"\r\n }\r\n ]\r\n}"},"url":"https://partnerships-sandbox.oneutilitybill.co/api/v1/leads","description":"Create a new lead resource.
\nWhen a tenancy start date is provided, it must be in Y-m-d format.
The provided address must be in either England, Scotland or Wales.
\nTo the provided email, we will apply RFC Validation, a DNS Check and a Spoof Check.
\nA phone number is required, but can be provided in national or E.164 format.
\nFor example:
\n\"phone_number\" : \"01916220102\"\n\"phone_number\" : \"+441916220102\"\nA country code may also be provided. If it is, it must be in ISO 3166-1 alpha-2 format.
\nFor example:
\n\"country_code\" : \"GB\",\n\"phone_number\" : \"07700900500\"\nIf a valid country code is provided, we will transform the phone number into the E.164 format by default before it is stored in our database. The above example would become +447700900500.
If no country code is provided, we will use the Google Phone Number library to try to determine where the phone number originates from.
\nIf successful, we will store the country code and transform the phone number as above. If unsuccessful, we will simply store the value you provide.
\nYou may also optionally provide any of the following national address identifiers to help us canonicalise the property:
\nproperty.uprn — Unique Property Reference Number (UPRN)property.umprn — Unique Multiple Residence Premise Reference Number (UMPRN)property.udprn — Unique Delivery Point Reference Number (UDPRN)If any of these identifiers are provided, we will use the corresponding address as formatted in the Royal Mail database (PAF) instead of the raw property.address_line_*, city, county, and postcode values you pass.
Fetches a single lead resource.
\n","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":"ID of the Lead
\n","type":"text/plain"},"type":"any","value":"01838daa-eb24-7c54-bac5-ca4eedab22f3","key":"leadId"}]}},"response":[{"id":"a3babb88-1848-4613-876e-9809e1c670a8","name":"Response_200","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":""},"url":{"raw":"https://partnerships-sandbox.oneutilitybill.co/api/v1/leads/:leadId","host":["https://partnerships-sandbox.oneutilitybill.co/api/v1"],"path":["leads",":leadId"],"variable":[{"id":"612aa7b2-d1ef-4e95-921f-ec9e5b7b3c9f","key":"leadId","value":"01838daa-eb24-7c54-bac5-ca4eedab22f3","description":"ID of the Lead"}]},"description":"Fetches a single lead resource.\n\n\nResponse Attribute | Type | Description\n------------------------------ | --------- | -----------\n`quote_id` | string | The quote_id related to this lead. May be null\n`tenancy_start_date` | string | The start date of the tenancy, provided in `Y-m-d` format. May be null\n`property.address_line_1` | string | The first line of the address\n`property.address_line_2` | string | The second line of the address. May be null\n`property.city` | string | The city where the property is located\n`property.county` | string | The county where the property is located. May be null\n`property.postcode` | string | A valid postcode within England, Scotland or Wales\n`contact.first_name` | string | A tenant's first name\n`contact.last_name` | string | A tenant's last name\n`contact.email_address` | string | A tenant's valid email address\n`contact.phone_number` | string | A tenant's phone number, usually in international format (see validation rules)\n`contact.country_code` | string | The country code associated with the tenant's phone number. May be null\n`created_at` | string | The datetime (UTC) when the lead was submitted to the Affiliate API\n"},"status":"Returns a single lead with the related contact and property data.","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json","disabled":false}],"cookie":[],"responseTime":null,"body":"{\r\n \"data\": {\r\n \"id\": \"01838daa-eb24-7c54-bac5-ca4eedab22f3\",\r\n \"quote_id\": \"01838de9-a331-7343-bd7a-e653ad9c3423\",\r\n \"tenancy_start_date\": \"2022-09-30\",\r\n \"property\": {\r\n \"id\": \"01838daa-eb24-7c54-bac5-ca4eedab22f3\",\r\n \"address_line_1\": \"5 Media Exchange\",\r\n \"address_line_2\": \"Coquet Street\",\r\n \"city\": \"Newcastle upon Tyne\",\r\n \"county\": \"Tyne and Wear\",\r\n \"postcode\": \"NE1 2QB\",\r\n \"uprn\": \"100110971828\",\r\n \"umprn\": \"1234567890\",\r\n \"udprn\": \"12345678\",\r\n \"created_at\": \"2022-09-30T09:13:36Z\",\r\n \"updated_at\": \"2022-09-30T09:13:36Z\"\r\n },\r\n \"contact\": {\r\n \"id\": \"01838daa-eb24-7c54-bac5-ca4eedab22f3\",\r\n \"first_name\": \"John\",\r\n \"last_name\": \"Smith\",\r\n \"email_address\": \"john.smith@oneutilitybill.co\",\r\n \"phone_number\": \"+447700964836\",\r\n \"country_code\": \"GB\",\r\n \"created_at\": \"2022-09-30T09:13:36Z\",\r\n \"updated_at\": \"2022-09-30T09:13:36Z\"\r\n },\r\n \"metadata\": [\r\n {\r\n \"id\": \"01838daa-eb24-7c54-bac5-ca4eedab22f3\",\r\n \"meta_key\": \"enquiry_id\",\r\n \"meta_value\": \"123\",\r\n \"created_at\": \"2022-09-30T09:13:36Z\",\r\n \"updated_at\": \"2022-09-30T09:13:36Z\"\r\n }\r\n ],\r\n \"created_at\": \"2022-09-30T09:13:36Z\",\r\n \"updated_at\": \"2022-09-30T09:13:36Z\"\r\n }\r\n}"}],"_postman_id":"f7469233-53e9-44d3-ad45-787a8d28f3b2"}],"id":"250bc64b-aad3-4a72-bba2-92558c82ab54","description":"Lead entities represent property data (ie a UK address), personal tenant data and, if provided,\na valid quote id, tenancy start date and metadata.
\n","_postman_id":"250bc64b-aad3-4a72-bba2-92558c82ab54","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":"Create a new quote resource.
\n","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":"Quote entities represent a total monthly cost, quote items with costs and metadata.
\n","_postman_id":"d0d06e83-cc27-4880-b849-b88037ddfb90","auth":{"type":"oauth2","oauth2":{"basicConfig":[],"advancedConfig":[{"key":"accessTokenUrl","value":"