Organization contacts

Each organization has a primary contact. You can create and modify organization contacts using Cloud API. When working with organizations and their contacts, you can:
  • Create a new organization contacts
  • Modify existing organization contacts
  • Modify an organization to use a new or existing contact as a primary contact

The endpoints for working with contacts described in this topic are found in the Common API. These endpoints can only be used for working with organization contacts. They cannot be used to work with account or policy contacts. If you want to work with account contacts or policy contacts, use the endpoints described in Account contacts and Policy contacts.

Create an organization contact

You can create contacts and set them to be the primary contacts for organizations using Cloud API.

When you create an organization contact, there is not a designated endpoint that is used to create the contact. (This differs from policy and account contacts, where there are specific endpoints for creating these types of contacts.) Instead, you must make two calls:
  • One call to create the contact
  • One call to patch the organization to set the created contact to its primary contact

You can do this using request inclusion to perform both actions in a single call, or you can make two separate calls. In either case, the criteria for creating the contact is described in Creating contacts.

Note that 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 The typelist editor for more.

Create a contact and set it as the primary contact for an organization

Using request inclusion, you can create a contact and set it to be the primary contact for an existing organization in a single call.

To do this, the call would need to execute two actions:
  • PATCH the primaryContactReference of the organization to use the refid of the contact that is POSTed in the included section
  • In the included section, POST the new contact with the refid specified in the primaryContactReference field

This is demonstrated in the following example:

Command
PATCH /admin/v1/organizations/pc:5
Request body
{
  "data": {
    "attributes": {
      "primaryContactReference": {
        "refid": "newperson"
      }
    }
  },
  "included": {
    "Contact": [
      {
        "attributes": {
          "firstName": "Sarah",
          "lastName": "Baker",
          "primaryAddress": {
            "addressLine1": "123 Hillsdale Blvd",
            "city": "San Mateo",
            "postalCode": "94403",
            "state": {
              "code": "CA"
            }
          },
          "subtype": {
            "code": "Person"
          }
        },
        "method": "post",
        "refid": "newperson",
        "uri": "/common/v1/contacts"
      }
    ]
  }
}

As a result of this call:

  • A new contact is created
  • The organization pc:5 has this contact as its primary contact

Set an organization’s primary contact to a user contact

You can set an organization’s primary contact to a user contact. This can only be done with users that meet the following criteria:
  • They are in the target organization
  • They have a valid user type in the UserType typelist

You can accomplish this the same way as setting an organization’s primary contact to any other contact: PATCH the organization to set the primaryContactReference field to the id of the user contact.

The following example demonstrates this, where the user contact with the id pc:490 is a user in the organization pc:6.

Command
PATCH /admin/v1/organizations/pc:6
Request body
{
  "data": {
    "attributes": {
      "primaryContactReference": {
        "id": "pc:490"
      }
    }
  }
}

Updating organization contacts

You can update organization contacts using Cloud API. Do this as described in Updating contacts.

Organization contact addresses

Organization contacts are created with a primary address. An organization contact can have only one primary address, but it can have multiple secondary addresses.

You can use Cloud API to add, update, and retrieve addresses on an organization contact. You can also replace a primary address with a secondary address, making the original primary address a secondary address.

This is done using endpoints in the Common API, as described in Contact addresses.