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
- required only if the contact is a
lastName
- required only if the contact is a
Person
or one of its subtypes
- required only if the contact is a
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.
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 stringpronounObjective
- the person’s objective pronoun, as a stringpronounPossessive
- 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.