Additional named insured contacts

Within the context of a policy, an additional named insured is a contact associated with the policy using the PolicyAddlNamedInsured role. A policy can have any number of additional named insureds.

The AdditionalNamedInsured resource

The additional named insured role is managed using a distinct resource type: AdditionalNamedInsured. This resource does not represent a policy contact. Rather, it represents that an existing policy contact has the PolicyAddlNamedInsured role. Like all other resources, the AdditionalNamedInsured resource has an id field. But this id is the id of the relationship, not of the contact itself.

For example, suppose a policy has two contacts: Ray Newton (id test_pp:1) and Helena Newton (id test_pp:3). Ray Newton is not an additional named insured. Helena is an additional named insured, and the id of the relationship is test_pp:707. For the policy:

  • Ray Newton, has the following resources:
    • A PolicyContact with id test_pp:1.
  • Helena Newton, has the following resources:
    • A PolicyContact with id test_pp:3.
    • An AdditionalNamedInsured with id test_pp:707.

The AdditionalNamedInsured resource includes a relationship property. This is an optional string used to identify the additional named insured's relationship to the primary insured, such as "spouse" or "roommate".

The AdditionalNamedInsured endpoints

The additional named insured role is managed using a set of /additional-named-insured endpoints. Note the following behaviors of the various GET endpoints:

  • If a contact does not have the additional named insured role:
    • The contact itself is returned by GET /contacts.
    • No relationship is returned by GET /additional-named-insureds.
  • If a contact does have the additional named insured role:
    • The contact itself is returned by GET /contacts.
    • The relationship is returned by GET /additional-named-insureds.

Querying for additional named insureds

Use the following endpoints to retrieve information about additional named insureds for a specific job:

  • GET /job/v1/jobs/{jobId}/additional-named-insureds
  • GET /job/v1/jobs/{jobId}/additional-named-insureds/{additionalNamedInsuredIdId}

These endpoints return only the policy contacts that have the additional named insured role on the job's underlying policy.

For example, the following is a portion of the response when querying for additional named insureds on job pc:4477.

GET /job/v1/jobs/pc:4477/additional-named-insured

{
    "count": 1,
    "data": [
        {
          "attributes": {
            "accountContact": {
              "displayName": "Helena Newton",
              "id": "test_pp:3"
            },
            "id": "test_pp:707",
            "relationship": "wife"
          }
        }
      ]
...

Adding additional named insureds

You can only add existing account contacts to a job as an additional named insured. To do so, use the following endpoint:

  • POST /job/v1/jobs/{jobId}/additional-named-insured

The request must include an accountContact property that specifies the ID of an existing account contact. It can also include an optional relationship property.

For example, the following request adds the existing account contact pc:4533 to job pc:4477. The additional named insured is designated as the "sister" of the primary insured.

POST /job/v1/jobs/pc:4477/additional-named-insured

{
  "data": {
    "attributes": {
        "accountContact": {
            "id": "pc:4533"
        },
        "relationship": "sister"
    }
  }
}

Updating additional named insureds

Use the following endpoint to PATCH an additional named insured:

  • PATCH /job/v1/jobs/{jobId}/additional-named-insured/{additionalNamedInsuredId}

The only field you can patch is relationship.

For example, the following request modifies the relationship of the additional named insured 309 on job pc:4477. 

PATCH /job/v1/jobs/pc:4477/additional-named-insured/309

{
  "data": {
    "attributes": {
        "relationship": "roommate"
    }
  }
}

Use the following endpoint to DELETE an additional named insured:

  • DELETE /job/v1/jobs/{jobId}/additional-named-insured/{additionalNamedInsuredId}

No request body is required.

This endpoint removes the Additional Named Insured role from the contact, but it does not delete the contact from the policy.

For example, the following request deletes additional named insured 309 on the underlying policy for job pc:4477. 

DELETE /job/v1/jobs/pc:4477/additional-named-insured/309

<no request body>

An additional named insured on a job or policy cannot be deleted while it is in use by a policy location. See Location named insureds for more information.