The following are the API methods available in the OneVu API.
In order to call the APIs you need the following setting to be enabled behind the scenes:
ApiKeySecurityEnabled
If you're licensed to use this functionality, you simply need to request this to be enabled via the support desk:
Once this has been enabled you will be able to create an API key which you can then use to call the APIs.
Creating an API Key
These are created within the API Developer Access screen within OneVu Control, as shown below:
Within here click Add to create an API Key. When you have you'll need to give it a name and description as shown below:
Note the name of the API key will be used when updating things for audit purposes. So it it is important to name these wisely.
When you click save you will be presented with a one time only view of the API Key and The API Key ID.
These are then used when calling the APIs.
Customer Methods
Finding a customer's details
This API will provide you with the name, address, email if their id is passed:
Departmental / Data (Card) Methods
OneVu's 'Cards' are the various departments presented in the 'Get Answers Fast' screen.
There are six API methods available as shown below:
Get customers/{customerId}/cards
To find out the departments available you simply need to provide this API with the customerId. This API provides a different 'cardId' for each department as well as Summary Fields to make it obvious as to what the department is.
This API will search OneVu to find the departments and content available for the user in question.
This provide details of:
the name and description of every department available
whether it is personalisable and whether it has been personalised
the direct links to the 'child' APIs for the customer to enable automated subsequent calling of these
the summary fields are shown on personalised cases. These will be things like the account/claim/case reference/postcode
It should be noted that IF a person has personalised more than 1 account/claim etc. within a silo, a separate card will be shown for EACH personalised account. E.g. the following was returned for the first personalised account in IEG4's own internal Council Tax app:
Get customers/{customerId}/cards/{cardId}/data-items
To find out the data items (the specific elements of data) within a given department you call this API using the customerId and the CardId that was retrieved in the /cards API method.
This will provide the actual values of all data items that would be used in personalised content within OneVu.
This API is useful for anyone wishing to access data from line of business applications in a consistent manner. The data items provided are all of the elements of data available for a department and these can be used to power a chatbot or external application.
The following shows an example response if we choose to select the Council Tax department.
What makes this impressive is that this is a JSON based rendering of the results of multiple Civica Council Tax API calls. So someone can build retrieve data from a legacy back office that uses legacy middleware and protocols using the latest/greatest standards.
Note that
the data is structured into groupings as configured in OneVu
the data format is presented in the format it was taken from the back office. This is to afford greater flexibility in how you want to show the data.
Get customers/{customerId}/cards/{cardId}/personalized-contents
This enables one to find out the high level FAQs and content in a department, which contain personalised data.
This API needs the customerId and the CardId that was retrieved in the /cards API method.
The following shows an example response if we choose to select the Council Tax department.
{
"title": "Council Tax",
"subTitle": "Information on Council Tax & register to view your Council Tax account online.",
"tiles": [
{
"title": "When am I next due to make a payment?",
"contents": "- Your next payment is due to be paid on this date: \n\n<time class=\"icon\">\n<em>Thursday</em>\n<strong>September</strong>\n<span class=\"time\">19</span>\n</time>\n\n- The amount to be paid is: <strong>£123.45</strong>\n- This will be taken by Direct Debit from bank account ending: <strong>1234****</strong>\n- This will continue every year unless you cancel it. So you don’t need to set it up again each year.\n- If you want to change the bank account details you can do this by using our online Direct Debit service.\n\n<a href=\"#/do-it-online/form/34\" class=\"btn btn-sm btn-primary\">Change my bank details</a>"
},
{
"title": "I'm moving house, what do I need to do?",
"contents": "You need to tell us if you're moving. It's quick and easy to report.\n \nTo tell us you're moving you'll need:\n- your previous address\n- your Council Tax number (if you're moving from one address to another in our area)\n- your new property address including postcode\n- the date of your move \n- details of buyers, sellers or agents\n\n<a href=\"#/do-it-online/form/35\" class=\"btn btn-sm btn-primary\">Tell us you're moving</a>\n\n\n"
}
]
}
Note that
Line breaks are indicated by \n
You may prefer to use the Get Data Items API (covered above) for greater flexibility
Get customers/{customerId}/cards/{cardId}/personalized-contents/tiles/{itemId}
This enables one to find out the specific detail of a personalised FAQ within a specific department.
This API needs the customerId, the CardId, and the itemId from those retrieved using the /personalized-contents API method.
Get customers/{customerId}/card-types/{cardTypeId}/static-contents
This enables one to find out the high level FAQs and content in a department, which contain static data.
This API needs the customerId and the CardId that was retrieved in the /cards API method.
The following shows an example response if we choose to select the Council Tax department.
{
"title": "Council Tax",
"subTitle": "Information on Council Tax & register to view your Council Tax account online.",
"tiles": [
{
"title": "I'm moving house, what do I need to do?",
"contents": "You need to tell us if you're moving. It's quick and easy to report.\n \nTo tell us you're moving you'll need:\n- your previous address\n- your Council Tax number (if you're moving from one address to another in our area)\n- your new property address including postcode\n- the date of your move \n- details of buyers, sellers or agents\n\n<a href=\"#/do-it-online/form/35\" class=\"btn btn-sm btn-primary\">Tell us you're moving</a>\n\n\n"
},
{
"title": "Since April, how much have I paid so far this year?",
"contents": "To view this, please complete the personalisation form."
},
{
"title": "How much is left to pay on this year's Council Tax?",
"contents": "To view this, please complete the personalisation form."
},
{
"title": "My circumstances have changed. What do I need to do?\n",
"contents": "If someone is moving into or out of your home, it may affect the amount of Council Tax you pay. You must let us know straight away.\n\n<a href=\"https://secure.west-norfolk.gov.uk/officeforms/change_of_circs.ofml\" target=\"_blank\" class=\"btn btn-sm btn-primary\">Notify us of a change</a>\n\n<b>Is it a change in personal details?</b>\n\nIf you've changed your name or any of your contact details you can let us know by completing our change in personal details form.\n\n<a href=\"#/do-it-online/form/1056\" class=\"btn btn-sm btn-primary\">Tell us about your change in personal details</a>\n"
},
{
"title": "I'm on a low income and can't afford to pay my Council Tax",
"contents": "You can claim Council Tax Support if you pay Council Tax and are on a low income.\n\nUsually you won't be able to claim if:\n\n- you're pension age and you and any partner have more than £16,000 in savings and investments (unless you receive the guarantee element of Pension Credit Savings Credit)\n- you're working age and you and any partner have more than £6,000 in savings (unless you are in a protected group)\n\nIf you're working age and have over £6,000 in savings, you may still be able to claim if you are in one of the following protected groups:\n\n- you have at least one child under the age of five in your household\n- you receive the Disability Premium or Disabled Child Premium when we calculate your weekly income allowance\n- you receive the Support Component of Employment Support Allowance\n- you receive or are entitled to Carer's Allowance\n\nTo make a claim for Council Tax Support you'll need to know:\n\n- your National Insurance number\n- your income\n- what is in your bank accounts\n- details of anyone living in your home\n\n<a href=\"#/do-it-online/form/2\" class=\"btn btn-sm btn-primary\">Claim Council Tax Support</a>\n"
}
]
}
Note that
Line breaks are indicated by \n
You will want to ensure that HTML is used as little as possible in static answers
Get customers/{customerId}/card-types/{cardTypeId}/static-contents/tiles/{itemId}
This enables one to find out the specific detail of a static FAQ within a specific department.
This API needs the customerId, the CardId, and the itemId from those retrieved using the /static-contents API method.
Registration Methods
The following are the API methods available to:
a) understand the data needed to authenticate for a given department
b) to actually authenticate a citizen
c) to de-register a citizen from having their personalised data shareable
Get customers/{customerId}/card-types/{cardTypeId}/registration-fields
In order to authenticate a person you need to know which fields are required to authenticate that person.
This time customerId and cardTypeId are needed with the following illustrating the response for the council tax department:
[
{
"fieldId": "8670792e-cd83-4649-b64b-e934bd42d5f1",
"label": "Last name",
"value": "",
"type": "StringFieldValue"
},
{
"fieldId": "eed0bde1-29e9-477b-86b2-aa91c982b6d4",
"label": "Account number - you can find this on any bills we have sent you",
"value": "",
"type": "StringFieldValue"
},
{
"fieldId": "ba5c503e-32ad-4d24-ac41-44a29384fc2f",
"label": "House number",
"value": "",
"type": "StringFieldValue"
},
{
"fieldId": "ee2f49d1-06e9-4433-996e-2d347c1d86af",
"label": "Postcode",
"value": "",
"type": "StringFieldValue"
}
]
Note that
In the above it is showing the exact label as it is held in the set up of OneVu. I.e. the second field is Account number but has some explanatory text beside it. This can be read and shown in your external app maximising consistency/reducing rework.
And this for Taxi Licensing:
[
{
"fieldId": "8670792e-cd83-4649-b64b-e934bd42d5f1",
"label": "Enter your surname here",
"value": "",
"type": "StringFieldValue"
},
{
"fieldId": "688ffbc2-1986-4fd8-97bd-650d5190e71b",
"label": "Enter your driving license number here",
"value": "",
"type": "StringFieldValue"
},
{
"fieldId": "ba5c503e-32ad-4d24-ac41-44a29384fc2f",
"label": "Enter your Taxi's Badge / Plate Number here",
"value": "",
"type": "StringFieldValue"
},
{
"fieldId": "ee2f49d1-06e9-4433-996e-2d347c1d86af",
"label": "Enter your Licensing Case reference here",
"value": "",
"type": "StringFieldValue"
}
]
I.e. irrespective of the back office you have a way in another application to know the fields required to authenticate someone.
Now we know which fields are required we can call the only (currently) one of these APIs that provides a post function - that which enables you to authenticate the customer for a department.
In order to authenticate a person we need to pass:
The customerId
The cardTypeId for the department being authenticated/linked to
a JSON payload containing the answers to the questions we got in the last API (Get Card Registration Fields)
In the above responses to the registration we were given the body of the request for this just missing the values. So we can take what we're given from Get Card Registration Details and simply place the answers the customer provides. In the example below we can see that the values have been provided in situ for a person with the surname Cooper, account no R987123D, House no 1a and Postcode SK9 7RR:
Post customers/{customerId}/card-types/{cardTypeId}/register
This is the API that enables a citizen to be authenticated against a back office application. In order to authenticate a person we need to pass:
The customerId
The cardTypeId for the department being authenticated/linked to
a JSON payload containing the answers to the questions we got in the last API (Get Card Registration Fields)
In the above responses to the registration we were given the body of the request for this just missing the values. So we can take what we're given from Get Card Registration Details and simply place the answers the customer provides. In the example below we can see that the values have been provided in situ for a person with the surname Cooper, account no R987123D, House no 1a and Postcode SK9 7RR:
[
{
"fieldId": "8670792e-cd83-4649-b64b-e934bd42d5f1",
"label": "Last name",
"value": "Cooper",
"type": "StringFieldValue"
},
{
"fieldId": "eed0bde1-29e9-477b-86b2-aa91c982b6d4",
"label": "Account number - you can find this on any bills we have sent you",
"value": "R987123D",
"type": "StringFieldValue"
},
{
"fieldId": "ba5c503e-32ad-4d24-ac41-44a29384fc2f",
"label": "House number",
"value": "1a",
"type": "StringFieldValue"
},
{
"fieldId": "ee2f49d1-06e9-4433-996e-2d347c1d86af",
"label": "Postcode",
"value": "SK9 7RR",
"type": "StringFieldValue"
}
]
When complete, the following successful response was returned for the above:
I.e. we have just authenticated a customer and linked their customerId to these details. The final API is one that allows us to unlink a user from an account.
This API will unlink an account/claim/case etc. from a person's identity. The only fields required for this API are customerId and cardId. So using the above cardId that was generated i.e. 250 and our customerId we can automatically unlink this.
On calling the Get Cards API again one can then see that this was removed.
Avoidable Contact Methods
The following are the different APIs available to retrieve and update the list of avoidable contact reasons:
Timeline Methods
There is currently one method and it enables entries to be added to the OneVu Timeline from external applications:
Broadcast Methods
The following are the API methods available in the context of Broadcast, which enable you to retrieve and update the notifications types available via Broadcast:
