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
    }
  }
}

Additional behaviors

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.

Specifying pronouns for contacts

For contacts of type Person or any of its subtypes, you can specify a set of pronouns on a contact. You can reference an existing set of pronouns from a typelist or input custom pronouns.

Use the pronounAggregate field to choose an existing set of pronouns from the PronounAggregateType typelist (for example, hehimhis). If different pronouns are desired, set this field to a value of selfidentify, and add pronouns using the following fields:
  • pronounSubjective - the person’s subjective pronoun, as a string
  • pronounObjective - the person’s objective pronoun, as a string
  • pronounPossessive - the person’s possessive pronoun, as a string

The values added to these fields are aggregated and used to populate the pronounAggregateDisplay field.

If the pronounAggregate field is changed from self-identify to one of the default values, the values in the pronounSubjective, pronounObjective, and pronounPossessive fields are cleared and set automatically. For example, if a value of sheherhers is input, pronounSubjective is set to She, pronounObjective is set to Her, and so on.