PolicyCenter contacts

PolicyCenter provides endpoints that allow you to work directly with contact information.

Some of these endpoints can only be used to work with contacts that are not account, policy, or job contacts. For example, to create organization contacts, you can use the POST /common/v1/contacts endpoint as explained below. But to create an account contact, you must use the POST /accounts/{accountId}/contacts endpoint, as explained in Creating account contacts.

Querying for contacts

You can retrieve a single contact by its id using the following endpoint:
  • GET /common/v1/contacts/{contactId}

For example:

Command

GET /common/v1/contacts/pc:83
Response
{
    "data": {
        "attributes": {
            "authorizationID": "wrightauthorizationid",
            "companyName": "Wright Construction",
            "displayName": "Wright Construction",
            "emailAddress1": "5678@guidewire.com",
            "emailAddress2": "5678@hotmail.com",
            "externalId": "pcext:53",
            "id": "test_pc:1",
            ...
        }
    }
}

Creating contacts

Create a contact using the following endpoint:
  • POST /common/v1/contacts

Minimum creation criteria

When creating a contact, you must specify the following information:
  • subtype (typically set to either person or company)
  • firstName and lastName (for Person contacts)
  • companyName (for Company contacts)
  • primaryAddress, with at least:
    • addressLine1
    • city
    • state
    • postalCode

A contact can be created as follows:

Command
POST /common/v1/contacts
Request body
{
    "data": {
        "attributes": {
            "firstName": "Jon",
            "lastName": "Wilson",
            "subtype": {
                "code": "person"
            },
            "primaryAddress": {
                "addressLine1": "193 Address Ln",
                "city": "San Mateo",
                "state": {
                    "code": "CA"
                },
                "postalCode": "94403"
            }
        }
    }
}

When this contact is created, it is not associated with a policy, account, or organization. It can now be set to be the primary contact for an organization.

In the base configuration, only contacts with subtypes person and company are supported. If you wish to add additional contact subtypes, you can extend the ContactType typelist. See Configuration Guide for more.

Updating contacts

You can update organization contacts using Cloud API. Do this using the following endpoint:
  • PATCH /common/v1/contacts/{contactId}

The following example updates a contact's work phone number.

Command
PATCH /common/v1/contacts/pc:934
Request body
{
    "data": {
        "attributes": {
            "workPhone": {
                "number": "801-202-2020"
            }
        }
    }
}

Search for contacts

Search for a contact

You can search for a single contact in PolicyCenter with the following endpoint:

  • POST /common/v1/search/contacts

In the request body, you must include information identifying the person or company contact you want to retrieve. The following attributes are required in the request:

  • For a person, provide one the following:
    • firstName and lastName
    • taxId
  • For a company, provide one of the following:
    • companyName
    • phoneNumber

This example retrieves the user named John Smith:

Command

POST /common/v1/search/contacts

Request

{
    "data": {
        "attributes": {
            "lastName": "Smith",
            "firstName": "John"
        }
    }
}

This example retrieves the company named Wright Construction:

{
    "data": {
        "attributes": {
            "companyName": "Wright Construction"
        }
    }
}

Destroy contact information

Destroying, or purging, is a form of data destruction that completely removes contact data from PolicyCenter. The Common API provides the following endpoints for data destruction actions on a contact:

  • POST /common/v1/contacts/{contactId}/destroy
  • POST /common/v1/contacts/{contactId}/do-not-destroy

For details on using these endpoints and more information on data destruction, see Destroying a contact

Contact addresses

You can retrieve, create, update, and delete contact addresses through Cloud API.

The endpoints described in this topic can be used when working with contacts that are not account, policy, or job contacts. To work with those types of contacts, you must work with endpoints described in Account contact addresses and Policy contact addresses.

Retrieve contact addresses

Use the following endpoints to retrieve a contact’s addresses:
  • GET /contacts/{contactId}/addresses
  • GET /contacts/{contactId}/addresses/{addressId}

For example, the following retrieves all addresses on a contact:

Command
GET /common/v1/contacts/pc:467/addresses
Response
{
    "count": 1,
    "data": [
        {
            "attributes": {
                "addressLine1": "193 Oak Way",
                "addressType": {
                    "code": "billing",
                    "name": "Billing"
                },
                "city": "San Mateo",
                "country": "US",
                "displayName": "193 Oak Way, San Mateo, CA 94403",
                "id": "pc:SKij3GqoHnes8Mkg_S4Ba",
                "postalCode": "94403",
                "primary": true,
                "state": {
                    "code": "CA",
                    "name": "California"
                }
            },
            ...
        }
    ],
    ...
}

Create a contact address

Create a new address on a contact using the following endpoint:
  • POST /common/v1/contacts/{contactId}/addresses

When you create an address on a contact, unless otherwise specified, it is added as a secondary address.

The following fields are required:
  • addressLine1 - The first line of the address, as a string
  • city - The name of the city, as a string
  • state - The state, as a typekey reference to the State typelist
  • postalCode - The postal code, as a string

The following is a minimal example:

Command
POST /common/v1/contacts/pc:532/addresses
Request body
{
  "data": {
    "attributes": {
      "addressLine1": "456 Hillsdale Blvd",
      "city": "Albany",
      "postalCode": "22222",
      "state": {
        "code": "CA"
      }
    }
  }
}

For organization contacts, if you want the address to be the primary address, set the primary field to true. When this field is set to true, the existing primary address automatically becomes a secondary address.

Update a contact address

You can update an address on a contact.

Do this using the following endpoint:
  • PATCH /common/v1/contacts/{contactId}/addresses/{addressId}

For example, the following updates a contact address to add addressLine2 and addressLine3 properties.

Command
PATCH /common/v1/contacts/pc:532/addresses/pc:873
Request body
{
  "data": {
    "attributes": {
      "addressLine2": "Building 4",
      "addressLine3": "Suite 200"
    }
  }
}

Delete a contact address

Use the following endpoint to delete a contact address:
  • DELETE /contacts/{contactId}/addresses/{addressId}

You cannot delete the primary address for a contact.

For example, the following command deletes a contact address. No request body is required.

Command

DELETE /common/v1/contacts/pc:532/addresses/pc:873