Policy period contacts

A policy period contact is a person or company that represents or is associated with a policy period. In the base configuration, policy periods are not required to have any contacts. For more information about policy period contacts, see the Application Guide.

You can query for, create, modify, and delete policy period contacts in Cloud API.

Retrieving policy period contacts

Use the following endpoints to retrieve information about policy period contacts:

  • GET billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/contacts
  • GET billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/contacts/{contactId}

For example, the following request retrieves all contacts for a specific policy period.

Command

GET /billing/v1/accounts/bc:16/policies/bc:45/policy-periods/bc:789/contacts

Response

{
  "count": 2,
  "data": [
    {
      "attributes": {                
        "authorizationID": "ShE2NeNioA510qsmq1AGF",
        "contactSubtype": "Person",
        "displayName": "Jon Johnson",
        "firstName": "Jon",
        "id": "bc:SObT3E_u_CmPF3rvGszii",
        "lastName": "Johnson"
      },
      ...
    },
    {
      "attributes": {                
        "authorizationID": "S_T-vXKIryDdGbF_yK2uH",
        "companyName": "Allrisk",
        "contactSubtype": "Company",
        "displayName": "Allrisk",
        "id": "bc:SEF2sUJjJPruTTbju2A0m",
        "roles": [
            {
                "code": "additionalinterest",
                "name": "Additional Interest"
            }
        ]
      },
      ...
    }
  ]
}

Creating policy period contacts

Use the following endpoint to create a new policy period contact:

  • POST /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/contacts

The following fields are required when creating a contact:

  • contactSubtype - Either person or company.
  • companyName - The name of the company (required only if the contact is a company).
  • lastName - The last name of the person (required only if the contact is a person).

The following example creates a new person contact:

Command

POST /billing/v1/accounts/bc:16/policies/bc:45/policy-periods/bc:789/contacts

Request body

{
  "data": {
    "attributes": {
      "contactSubtype": "person",
      "lastName": "Smith"
    }
  }
}

The following example creates a new company contact:

Command

POST /billing/v1/accounts/bc:16/policies/bc:45/policy-periods/bc:789/contacts

Request body

{
  "data": {
    "attributes": {
      "contactSubtype": "company",
      "companyName": "Tech Solutions"
    }
  }
}

If BillingCenter is integrated with a contact management system, you can use the field syncAddressBookUID to copy over a contact from the contact management system. For more, see Creating contacts from a contact management system.

Updating policy period contacts

Use the following endpoint to update an existing policy period contact:

  • PATCH /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/contacts/{contactId}

The following example updates the last name of a person contact:

Command

PATCH /billing/v1/accounts/bc:16/policies/bc:45/policy-periods/bc:789/contacts/bc:1236

Request body

{
  "data": {
    "attributes": {
      "lastName": "Johnson"
    }
  }
}

Deleting policy period contacts

Use the following endpoint to delete a policy period contact:

  • DELETE /billing/v1/accounts/{accountId}/policies/{policyId}/policy-periods/{policyPeriodId}/contacts/{contactId}

The following example deletes a contact:

Command

DELETE /billing/v1/accounts/bc:16/policies/bc:45/policy-periods/bc:789/contacts/contact:123