Companies

Companies Endpoint Reference

Companies represent the organization to which lead records belong.  Leads are added to a
Company by populating their corresponding externalCompanyId field using Sync Leads or Bulk Lead Import endpoints.  Once a lead has been added to a company, you cannot delete the lead from that company (unless you add the lead to a different company).  Leads linked to a company record will directly inherit the values from a company record as though the values existed on the lead’s own record.

Company APIs are only exposed for subscriptions which do not have a native CRM sync enabled.

.

Describe

Describing the company object will give you all the information you need to interact with them.

Query

The pattern for querying companies closely follows that of the leads API with the added restriction that the filterType parameter accepts the fields listed in the searchableFields array of the Describe Companies call, or dedupeFields.

filterType and filterValues are required query parameters.  fields, nextPageToken, and batchSize are optional parameters.  The parameters function just like the corresponding parameters in the Leads and Opportunities APIs.  When requesting a list of fields, if a particular field is requested, but not returned, the value is implied to be null.

If the fields parameter is omitted, the default set of fields returned is:

  • id
  • dedupeFields
  • updatedAt
  • createdAt

Create and Update

The Sync Companies endpoint accepts the required input parameter that contains an array of company objects.  Just like opportunities, there are three modes for creating and updating companies: createOnly, updateOnly, and createOrUpdate.  Modes are specified in the action parameter of the request.  Both the dedupeBy and action parameters are optional, and default to the dedupeFields and the createOrUpdate modes respectively.

Fields

The company object contains a set of fields.  Each field definition is comprised of a set of attributes that describe the field.  Examples of attributes are display name, API name, and dataType.  These attributes are known collectively as metadata.

The following endpoints allow you to query fields on the company object. These APIs require that the owning API user have a role with one or both of the Read-Write Schema Standard Field or Read-Write Schema Custom Field permissions.

Query Fields

Querying company fields is straightforward.  You may query a single company field by API name or query the set of all company fields.

By Name

The Get Company Field by Name endpoint retrieves metadata for a single field on the company object.  The required fieldApiName path parameter specifies the API name of the field.  The response is like the Describe Company endpoint but contains additional metadata such as the isCustom attribute which denotes whether the field is a custom field.

Browse

The Get Company Fields endpoint retrieves metadata for all fields on the company object.  By default, a maximum of 300 records are returned.  You can use the batchSize query parameter to reduce this number.  If the moreResult attribute is true, this means more results are available.  Continue to call this endpoint until the moreResult attribute returns false, which means there are no results available.  The nextPageToken returned from this API should always be reused for the next iteration of this call.

Delete

The deletion criteria is specified in the input array, which contains a list of search values.  The deletion method is specified in the deleteBy parameter.  Permissible values are: dedupeFields, idField.  Default is dedupeFields.