The bulk upsert endpoints accept an array of objects to be upserted (created and/or updated).

To decide if an object will be inserted/created or updated, we first try to match it with existing records in Planhat.

This matching can be based on a few different keyables (keys used by Planhat to identify resources), typically:

• _id: Planhat native id.

• sourceId: id from some external systems e.g. your CRM.

• externalId: id in your own system.

The exact keyable available depends on the resource in question and these are listed under each section here in the docs.

If no keyable is provided, or if the provided key doesn't match any existing record a new record will be created, assuming minimum required information is provided.

Generally very few fields are required, for example you are allowed to create a contact without providing first or last name.

The one exception is that most objects must be associated with a company profile in Planhat, which means that you'll need to provide a Planhat companyId to create most objects.

To make an update you typically don’t need to provide companyId since the record already exists and is mapped to a company profile.

For an update to make sense it should contain at least one keyable to be used for matching and at least one property to be updated.

Properties that are used as keyable can only be updated by providing a higher priority key.

In general the hierarchy of keyables are: _id > sourceId > externalId.

Note: For the Enduser model the keyables hierarchy is:
_id > sourceId > externalId > email.

The bulk upsert operation responds with an object containing different properties each of which has some valuable information.

• created: Number of elements created.

• createdErrors: Array of error objects specifying the detail why a create attempt failed.

• insertsKeys: Array of objects containing the inserted keys for each created element.

• updated: Number of elements updated.

• updatedErrors: Array of error objects specifying the detail why an update attempt failed.

• updatesKeys: Array of objects containing the modified keys for each updated element.

• nonupdates: Number of elements that were not updated.

• modified: Array of ids of updated elements.

• upsertedIds: Array of ids of created elements.

• permissionErrors: Array of objects containing the detail why a create or update attempt failed due to a permission problem.

Example:

This may find a contact with externalId equal to 123 and then set firstName to Luke.

But because externalId is used for matching it will not be updated.

To update externalId in this case you'll need to provide a matching sourceId or planhatId (_id).

Example:

If this were the same record as above (based on planhatId) then it would update externalId from 123 to 999.

Reduced payload to perform identical updates of multiple documents.

- Error due to a missing required parameter

- Error due to an invalid object ID

- Error due to an invalid type

Note: For all bulk upsert operations, regardless of the model, there is an upper limit of 5,000 items per request.