Account contacts

An account can have any number of contacts.

Querying for account contacts

Use the following endpoints to retrieve information about contacts for a specific account:

  • GET /accounts/{accountId}/contacts
  • GET /accounts/{accountId}/contacts/{contactId}

Masking the taxID field

The BillingContact resource has a taxID field which stores the tax id of the contact. In the Cloud API base configuration, this field is masked in responses so that only the last four digits appear. For example, the following is the response for a GET that retrieves a contact.

{
  "data": {
    "attributes": {
      "displayName": "Ray Newton",
      "taxId": "***-**-6789"
    }
  }
}

For some callers, such as internal or external users, the masking of tax id may be appropriate as it protects personally identifiable information. For other callers, such as services, this masking may cause a problem as the callers may reference contacts internally using the tax id.

There are two ways that the taxId field can be unmasked:

  • You can configure the field so that it is always unmasked. For information on how to configure this, see Obfuscating response data.
  • You can grant the caller the restunmasktaxid system permission. Any caller who has a role with this permission will get responses with unmasked tax IDs. For information on how to configure this, see the section on API role special permissions in the Cloud API Developer Guide.

Creating account contacts

Use the following endpoint to create a contact for a given account:

  • POST /accounts/{accountId}/contacts

Minimum creation criteria

At a minimum, you must specify the following information:

  • contactSubtype
  • companyName
    • required only if the contact is a Company or one of its subtypes
  • lastName
    • required only if the contact is a Person or one of its subtypes
  • primaryPayer

For example, the following payload creates a new contact with the minimum required fields and one optional field (firstName):

POST billing/v1/accounts/bc:7123/contacts

{
  "data": {
    "attributes": {
        "contactSubtype": "Person",
        "firstName": "Matt",
        "lastName": "Hamilton",
        "primaryPayer": false
    }
  }
}

POSTing contacts and the primaryPayer flag

The BillingCenter user interface requires every account to have exactly 1 contact with the primaryPayer flag set to true. This requirement is enforced in the user interface only and not in the database. The database allows an account to have any number of primaryPayer contacts, from 0 to more than 1.

Cloud API prevents an account from having more than 1 primaryPayer contact. However, Cloud API does not prevent an account from having no primaryPayer contacts. In fact, having no primaryPayer contacts is a required intermediate stage when changing which contact is the primary payer.