Update a policyholder

patch https://sandbox.uk.rootplatform.com/v1/insurance/policyholders/{policyholder_id}

Path Params

policyholder_id

string

required

Must be a UUID. The unique identifier of the policyholder.

Body Params

object

(Individual policyholders only) Object containing policyholder's identification information.

initials

string

The new initials for the policyholder. This replaces the policyholder's current initials.

title

string

The policyholders's title.

first_name

string

A new first name for the policyholder. This replaces the policyholder's current first name.

middle_name

string

The policyholder or primary contact's legal middle name.

last_name

string

A new last name for the policyholder. This replaces the policyholder's current last name.

expiration_date

date-time

(Individual policyholders only) The expiration date of the policyholder's passport or custom identifier.

string

A new contact email for the policyholder. This replaces the policyholder's current email address.

cellphone

phone_other

app_data

object | null

null is allowed. An object containing additional custom data for the policy holder.

address

object | null

null is allowed. The policyholder's physical address. See below for more details.

Response

Response body

object

policyholder_id

string

required

Must be a UUID. The unique identifier of the policyholder.

type

string

required

The policyholder type.

individual company

object

required

(Individual policyholders only) Object containing policyholder's identification information.

type

string

required

The id type of the policyholder.

id passport email cellphone custom

number

string

required

The ID or passport number.

country

string

required

The ISO Alpha-2 country code of the country of the id/passport number.

expiration_date

date-time

(Individual policyholders only) The expiration date of the policyholder's passport.

title

string

The policyholders's title.

mr mrs miss mx sir dr adv ms prof

date_of_birth

string

(Individual policyholders only) The policyholder's date of birth in the format YYYYMMDD.

gender

string

Null is allowed. (Individual policyholders only) The policyholder's gender.

male female

initials

string | null

null is allowed. The policyholder or primary contact's initials.

first_name

string

required

The policyholder or primary contact's legal first name.

middle_name

string | null

null is allowed. The policyholder or primary contact's legal middle name.

last_name

string

required

The policyholder or primary contact's legal last name.

string | null

null is allowed. The policyholder or primary contact's contact email address.

cellphone

string | null

null and "" allowed. String containing the cellphone number in international format.

phone_other

string | null

null and "" allowed. String containing the cellphone number in international format.

policy_ids

array of strings

required

An array of ids of the policies linked to this policyholder.

policy_ids*

policies

array of objects

An array of full policy objects owned by the policyholder. This is currently only included when fetching all policyholders or fetching an individual policyholder with ?include=policies.

policies

object

policy_id

string

required

Must be a UUID. Object ID of the policy.

policy_number

string

required

A shorter, human-readable policy identifier. This typically used in policy documents and customer notifications for ease of reference.

status

string

required

The policy status. See the managing policies guide for more details on the policy lifecycle.

pending_initial_payment active cancelled expired lapsed not_taken_up

policyholder_id

string

required

Must be a UUID. The system identifier of the policy's policyholder.

package_name

string

required

The insurance package name.

sum_assured

integer

The amount, in cents, of the maximum value insured.

monthly_premium

integer

required

The total monthly premium, in cents, that will be billed to the policyholder.

billing_amount

integer

required

The amount, in cents, that will be billed on the next billing run.

balance

integer

required

The amount, in cents, that is owed on the policy. If the policyholder makes an adhoc payment to the policy, the amount is credited to this balance. If the policyholder defaults on a payment, it is subtracted from the balance. If the balance is found negative during the next billing run, the amount is added to the monthly premium, else the monthly premium is subtracted from the balance and the remainder is charged.

billing_day

integer | null

required

null is allowed. The day of month on which the policy is billed. Should be between 1 and 31, or null. If it falls on a day that does not exist in the month (for example, 31 in February) the policy will be billed on the last day of the month. Setting this value to 31 will ensure that the policy is billed on the last day of every month.

billing_frequency

string

required

The frequency at which the policy is billed. One of [monthly, yearly, once_off]. See the billing settings guide for more details on the billing frequency.

next_billing_date

date-time

required

The next date the policy is due to be billed.

currency

string

required

The currency code of the policy.

beneficiaries

An array of beneficiaries, or "null".

covered_people

array of objects | null

required

null is allowed. An array of covered people added to the policy.

covered_people*

object

base_premium

integer

required

The amount, in cents, of the minimum allowed monthly premium fee. This includes risk pricing and platform fees.

claim_ids

array of strings

required

An array of claim ids of the claims linked to the policy.

claim_ids*

complaint_ids

array of strings

required

An array of complaint ids of the complaints linked to the policy.

complaint_ids*

start_date

date-time

required

Once the policy reaches its start date, cover commences and regular collection attempts can run against the policy (provided it has an active status). See the Managing policies guide for more details on the policy lifecycle.

end_date

date-time

required

When the policy reaches its end date, its status will change to expired. Cover and collections will cease. Policies with no end date do not expire.

current_version

integer | null

null is allowed. The current policy schedule version.

schedule_file_id

string | null

null is allowed. Object ID of the policy document.

policy_schedule_uri

string | null

required

URI to the policy document in PDF format.

terms_file_id

string | null

null is allowed. Attachment ID of the policy terms document.

terms_uri

string | null

required

URI to the terms document in PDF format.

supplementary_terms_files

array of objects

required

Supplementary terms files associated with the policy.

supplementary_terms_files*

object

supplementary_terms_file_id

string

Attachment ID of the supplementary terms document.

type

string

The supplementary terms file type, as specified in the product module settings.

uri

string

URI to the supplementary terms document in PDF format.

policy_welcome_letter_file_id

string | null

null is allowed. Object ID of the welcome letter.

policy_welcome_letter_uri

string | null

null is allowed. URI to the welcome letter in PDF format.

policy_certificate_file_id

string | null

null is allowed. Object ID of the policy certificate.

policy_certificate_uri

string | null

null is allowed. URI to the certificate in PDF format.

policy_anniversary_file_id

string | null

null is allowed. Object ID of the policy anniversary document.

schedule_versions

array of objects

required

The policy schedule versions for the policy. A new policy schedule version is typically created when the policy is updated.

schedule_versions*

object

version

integer

The policy schedule version number.

created_at

date-time

The date the policy schedule version was created.

created_at

date-time

required

The time at which the policy was created.

module

object

required

Custom, product-specific fields stored against the policy. These parameters are set in the policy issue hook in the product module code. They can be referenced in policy documents, data exports and external integrations.

Has additional fields

app_data

object | null

required

null is allowed. An object containing additional custom data for the policy.

Has additional fields

created_by

object | null

required

null is allowed. An object indicating the user or API key that created the policy.

Has additional fields

scheme_type

string

required

Indicates the policy scheme type, being either individual or group.

payment_method_id

string

Must be a UUID. The ID of the policy's payment method, if set.

charges

array of objects

required

Whenever a premium payment is created (including reversals), a breakdown of the payment amount is calculated according to the charges stored on the policy. This allows the premium breakdown to be referenced in policy documents and disclosures, and in the policy's payment data. See the policy issue hook guide for more details on charges and commissions.

charges*

object

type

string

required

Variable charges are applied as a proportion of the total payment amount. Fixed charges are applied as an absolute currency value in cents. The balance is the balance of the payment total after all charges have been applied.

fixed variable balance

name

string

required

The name of the charge.

description

string

The description of the charge.

amount

integer

The charged amount. Required when type is fixed or variable. Either a proportion of the total premium (if type is variable), or a currency amount in cents (if type is fixed).

created_at

date-time

required

The time at which the policyholder was created.

app_data

object | null

required

null is allowed. An object containing additional custom data for the policy holder.

Has additional fields

created_by

object | null

required

null is allowed. An object indicating the user or API key that created the policyholder. See Authentication.

Has additional fields

address

object | null

null is allowed. The policyholder's physical address. See below for more details.

line_1

string

required

First line of the policyholder's address.

line_2

string | null

null is allowed. Optional second line of the policyholder's address.

suburb

string

The policyholder's suburb.

city

string

required

The policyholder's city.

country

string

required

The policyholder's country code, in the ISO Alpha-2 format.

area_code

string

required

The policyholder's area code must be 4 characters long for South African addresses.

Language

Credentials

Basic

base64

URL


xxxxxxxxxx
1
curl --request PATCH \
2
     --url https://sandbox.uk.rootplatform.com/v1/insurance/policyholders/policyholder_id \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json' \
5
     --data '{"id":{"type":"id"}}'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Success