Using Metadata
Most often, when you are getting started with the Claims Manager Api, you will know the fields that you want to pass to us when notifying us of a claim. We'll now take a look at an example of how we can use the incident metadata response and match the fields we are interested in via the Claims Manager front end to build up our request message.
If we take a look at an existing Motor incident on the Demonstration Programme in Claims Manager, we can pick the fields that we want to pass data to.
<
We'll add data to the Incident Location and Incident Country fields on the Details tab.
We'll also add data for the Cause Code 1 and Cause Code 2 fields on the Codes tab.
And finally, we'll add data for the Driver First Name, Driver Last Name, Vehicle Registration and Vehicle Type fields on the Motor Details tab.
Reviewing the metadata
First, let's call the metadata/incidents endpoint with the correct parameters to see the full list of available fields on this screen. In order to call
this endpoint, we need to pass in the programmeCode, policyTypeCode and countryCode for the type of incident we are interested in.
For our example here, we are looking at a Motor incident on the Demonstration programme for a policy country of the United Kingdom. We can get the various codes we need
from the metadata/programmes endpoint, see the Make your first request page for a reminder. Let's go ahead and
call the endpoint with the relevant codes:
curl --location --request GET 'https://api.claimsmanagertest.crawco.co.uk/metadata/incidents?programmeCode=8ffd4f55&policyTypeCode=17ed9895&countryCode=GB' \
--header 'Authorization: Bearer {access token}'Remember to replace the {access token} placeholder with a valid access token retrieved from the authentication endpoint.
From the returned list of fields, we now need to search for the fields we are interested in. We can use the section and name properties
to help us match these up to what we see in the front end. If we start with the Details tab shown above, we're looking for fields called Incident Location
and Incident Country with a section of Details.
{
"identifier": "Global_Incident_Form:Incident_Location",
"mapsTo": "extendedFields",
"name": "Incident Location",
"section": "Details",
"dataType": "string",
"maxLength": 250,
"isRequired": true,
"listSource": null
},
{
"identifier": "Global_Incident_Form:Incident_Country",
"mapsTo": "extendedFields",
"name": "Incident Country",
"section": "Details",
"dataType": "string",
"maxLength": null,
"isRequired": false,
"listSource": [
"Afghanistan",
"Åland Islands",
"Albania",
"Algeria",
"American Samoa",
"Andorra",
"Angola",
"Anguilla",
"Antarctica",
"Antigua and Barbuda",
"Argentina",
"Armenia",
"Aruba",
"Australia",
"Austria",
"Azerbaijan",
"Bahamas",
"Bahrain",
"Bangladesh",
"Barbados",
"Belarus",
"Belgium",
"Belize",
"Benin",
"Bermuda",
"Bhutan",
"Bolivia, Plurinational State of",
"Bonaire, Sint Eustatius and Saba",
"Bosnia and Herzegovina",
"Botswana",
"Bouvet Island",
"Brazil",
"British Indian Ocean Territory",
"Brunei Darussalam",
"Bulgaria",
"Burkina Faso",
"Burundi",
"Cabo Verde",
"Cambodia",
"Cameroon",
"Canada",
"Cayman Islands",
"Central African Republic",
"Chad",
"Chile",
"China",
"Christmas Island",
"Cocos (Keeling) Islands",
"Colombia",
"Comoros",
"Congo",
"Cook Islands",
"Costa Rica",
"Côte d'Ivoire",
"Croatia",
"Cuba",
"Curaçao",
"Cyprus",
"Czech Republic",
"Democratic Republic of the Congo",
"Denmark",
"Djibouti",
"Dominica",
"Dominican Republic",
"Ecuador",
"Egypt",
"El Salvador",
"Equatorial Guinea",
"Eritrea",
"Estonia",
"Ethiopia",
"Falkland Islands",
"Faroe Islands",
"Fiji",
"Finland",
"France",
"French Guiana",
"French Polynesia",
"French Southern Territories",
"Gabon",
"Gambia",
"Georgia",
"Germany",
"Ghana",
"Gibraltar",
"Greece",
"Greenland",
"Grenada",
"Guadeloupe",
"Guam",
"Guatemala",
"Guernsey",
"Guinea",
"Guinea-Bissau",
"Guyana",
"Haiti",
"Heard Island and McDonald Islands",
"Holy See",
"Honduras",
"Hong Kong",
"Hungary",
"Iceland",
"India",
"Indonesia",
"Iran",
"Iraq",
"Ireland",
"Isle of Man",
"Israel",
"Italy",
"Jamaica",
"Japan",
"Jersey",
"Jordan",
"Kazakhstan",
"Kenya",
"Kiribati",
"Korea (the Democratic People's Republic of)",
"Korea (the Republic of)",
"Kosovo",
"Kuwait",
"Kyrgyzstan",
"Lao People's Democratic Republic",
"Latvia",
"Lebanon",
"Lesotho",
"Liberia",
"Libya",
"Liechtenstein",
"Lithuania",
"Luxembourg",
"Macao",
"Macedonia",
"Madagascar",
"Malawi",
"Malaysia",
"Maldives",
"Mali",
"Malta",
"Marshall Islands",
"Martinique",
"Mauritania",
"Mauritius",
"Mayotte",
"Mexico",
"Micronesia",
"Moldova",
"Monaco",
"Mongolia",
"Montenegro",
"Montserrat",
"Morocco",
"Mozambique",
"Myanmar",
"Namibia",
"Nauru",
"Nepal",
"Netherlands",
"New Caledonia",
"New Zealand",
"Nicaragua",
"Niger",
"Nigeria",
"Niue",
"Norfolk Island",
"Northern Mariana Islands",
"Norway",
"Oman",
"Pakistan",
"Palau",
"Palestine, State of",
"Panama",
"Papua New Guinea",
"Paraguay",
"Peru",
"Philippines",
"Pitcairn",
"Poland",
"Portugal",
"Puerto Rico",
"Qatar",
"Réunion",
"Romania",
"Russian Federation",
"Rwanda",
"Saint Barthélemy",
"Saint Helena, Ascension and Tristan da Cunha",
"Saint Kitts and Nevis",
"Saint Lucia",
"Saint Martin (French part)",
"Saint Pierre and Miquelon",
"Saint Vincent and the Grenadines",
"Samoa",
"San Marino",
"Sao Tome and Principe",
"Saudi Arabia",
"Senegal",
"Serbia",
"Seychelles",
"Sierra Leone",
"Singapore",
"Sint Maarten (Dutch part)",
"Slovakia",
"Slovenia",
"Solomon Islands",
"Somalia",
"South Africa",
"South Georgia and the South Sandwich Islands",
"South Sudan",
"Spain",
"Sri Lanka",
"Sudan",
"Suriname",
"Svalbard and Jan Mayen",
"Swaziland",
"Sweden",
"Switzerland",
"Syrian Arab Republic",
"Taiwan",
"Tajikistan",
"Tanzania, United Republic of",
"Thailand",
"Timor-Leste",
"Togo",
"Tokelau",
"Tonga",
"Trinidad and Tobago",
"Tunisia",
"Turkey",
"Turkmenistan",
"Turks and Caicos Islands",
"Tuvalu",
"Uganda",
"Ukraine",
"United Arab Emirates",
"United Kingdom",
"United States",
"United States Minor Outlying Islands",
"Uruguay",
"Uzbekistan",
"Vanuatu",
"Venezuela, Bolivarian Republic of ",
"Viet Nam",
"Virgin Islands (British)",
"Virgin Islands (U.S.)",
"Wallis and Futuna",
"Western Sahara",
"Yemen",
"Zambia",
"Zimbabwe"
]
}
The relevant metadata fields are shown above. We can use this data to determine how we add these fields to the extendedFields array of our request.
For the Incident Location field, we can see that this has an identifier of 'Global_Incident_Form:Incident_Location'. If we wanted to populate
this field with a value of 'London', we would add the following item to the extendedFields array:
{
"identifier": "Global_Incident_Form:Incident_Location",
"value": "London"
}
For the Incident Country field, we can see that this has an identifier of 'Global_Incident_Form:Incident_Country'. We can also see that this field has
a listSource array of possible values. In the Claims Manager application this field is a drop down list and the list source array contains all of the possible values.
When we pass this field in the extendedFields array, the value property must be one of the these list source values:
{
"identifier": "Global_Incident_Form:Incident_Country",
"value": "United Kingdom"
}Note that if the value property is not one of the options in the listSource array, a validation error will be returned when making the request.
Moving on to the Codes tab, we are now looking for two fields called Cause Code 1 and Cause Code 2 with a section of Codes.
{
"identifier": "Global_Incident_Form:Cause_Code1",
"mapsTo": "extendedFields",
"name": "Cause Code 1",
"section": "Codes",
"dataType": "string",
"maxLength": null,
"isRequired": true,
"listSource": [
"Accidental Damage",
"Animal",
"Chemicals, Radiation, caustics, toxics",
"Collision or Impact",
"Cut or puncture",
"Earthquake",
"Explosion",
"Falling objects",
"Fire or Heat",
"Flood",
"Glass",
"Interior abuse",
"Property Damage",
"Storm Damage",
"Strikes, riots, civil commotions",
"Subsidence, Ground Heave, Landslip",
"Theft or Burglary",
"Vandalism",
"Vehicle Damage"
]
},
{
"identifier": "Global_Incident_Form:Cause_Code2",
"mapsTo": "extendedFields",
"name": "Cause Code 2",
"section": "Codes",
"dataType": "string",
"maxLength": null,
"isRequired": true,
"listSource": [
"Bodily defects (defective hearing, eyesight etc.)",
"Driver fault unknown",
"Driving too fast for road, weather conditions",
"Driving under influence of alcohol",
"Driving with revoked/suspended/denied license",
"Failure to Allow Adequate Clearance - Side to side, Backing Up, Overhead Clearance",
"Failure to secure vehicle (left key in/unlocked)",
"Failure to slow down for cross traffic",
"Failure to yield right of way",
"Following too Closely, Rear or Front End Collision",
"Hit and run, leaving the scene of accident",
"Improper attitude (disregard of instructions etc.)",
"Improper physical condition (tired, worried etc.)",
"Improper placement or position",
"Lack of adequate preventive maintenance",
"Lack of knowledge, skill, experience, training",
"Loss of control",
"Malfunction",
"Miscellaneous, no applicable code",
"No apparent improper driving",
"Operating contrary to directions or instructions",
"Operating or working at an unsafe speed",
"Other - insured operation",
"Overloading",
"Traffic control violated",
"Vehicle accidentally set in motion",
"Vehicle separation"
]
}
Again, both of these fields have a listSource defined, so the values we pass for these must be one of the options given. If we want to add 'Accidental Damage' for
Cause Code 1 and 'Loss of control' for Cause Code 2, our extendedFields for these fields should look like:
{
"identifier": "Global_Incident_Form:Cause_Code1",
"value": "Accidental Damage"
},
{
"identifier": "Global_Incident_Form:Cause_Code2",
"value": "Loss of control"
}
Finally, we need the Driver First Name, Driver Last Name, Vehicle Registration and Vehicle Type fields with a section of 'Motor Details'. Below we can see these
fields in the metadata response, and then how we will pass these in the extendedFields array:
{
"identifier": "Global_Incident_Form:Driver_First_Name",
"mapsTo": "extendedFields",
"name": "Driver First Name",
"section": "Motor Details",
"dataType": "string",
"maxLength": 50,
"isRequired": true,
"listSource": null
},
{
"identifier": "Global_Incident_Form:Driver_Last_Name",
"mapsTo": "extendedFields",
"name": "Driver Last Name",
"section": "Motor Details",
"dataType": "string",
"maxLength": 50,
"isRequired": true,
"listSource": null
},
{
"identifier": "Global_Incident_Form:Vehicle_Registration",
"mapsTo": "extendedFields",
"name": "Vehicle Registration",
"section": "Motor Details",
"dataType": "string",
"maxLength": 50,
"isRequired": true,
"listSource": null
},
{
"identifier": "Global_Incident_Form:Vehicle_Type",
"mapsTo": "extendedFields",
"name": "Vehicle Type",
"section": "Motor Details",
"dataType": "string",
"maxLength": null,
"isRequired": true,
"listSource": [
"Bicycle",
"Bus / Coach",
"Mobile Home",
"Motor Bike",
"Motor Car",
"Rigid",
"Scooter",
"Specialist Vehicle",
"Taxi",
"Tractor",
"Trailer"
]
}{
"identifier": "Global_Incident_Form:Driver_First_Name",
"value": "John"
},
{
"identifier": "Global_Incident_Form:Driver_Last_Name",
"value": "Smith"
},
{
"identifier": "Global_Incident_Form:Vehicle_Registration",
"value": "AB12 CDE"
},
{
"identifier": "Global_Incident_Form:Vehicle_Type",
"value": "Motor Car"
}Putting it all together
Now that we've located all of the fields that we want to populate with data and mapped these to the extendedFields array, we can add this to the basic incident
request that we used in the Create an incident tutorial to create a new incident with these extra fields set.
curl --location --request POST 'https://api.claimsmanagertest.crawco.co.uk/Incidents' \
--header 'Authorization: Bearer {access token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"programmeCode": "8ffd4f55",
"policyCountry": "GB",
"policyTypeCode": "17ed9895",
"incidentDate": "2022-04-01",
"description": "Test incident from Claims Manager Api",
"extendedFields": [
{
"identifier": "Global_Incident_Form:Incident_Location",
"value": "London"
},
{
"identifier": "Global_Incident_Form:Incident_Country",
"value": "United Kingdom"
},
{
"identifier": "Global_Incident_Form:Cause_Code1",
"value": "Accidental Damage"
},
{
"identifier": "Global_Incident_Form:Cause_Code2",
"value": "Loss of control"
},
{
"identifier": "Global_Incident_Form:Driver_First_Name",
"value": "John"
},
{
"identifier": "Global_Incident_Form:Driver_Last_Name",
"value": "Smith"
},
{
"identifier": "Global_Incident_Form:Vehicle_Registration",
"value": "AB12 CDE"
},
{
"identifier": "Global_Incident_Form:Vehicle_Type",
"value": "Motor Car"
}
]
}'
The response for the request above will contain the incidentId of the newly created incident which we can use to lookup the result in Claims Manager.
We can see that all of the fields that we set values for in the extendedFields array have been populated with the correct data.
