Companies

Last update: June 5, 2024

CREATED FOR:

  • Admin

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 read-only access for subscriptions which have SFDC Sync or Microsoft Dynamics Sync are enabled.

Describe

Describing the company object gives you all the information you must interact with them.

GET /rest/v1/companies/describe.json

{
   "success":true,
   "requestId":"5847#14d44113ad7",
   "result":[
      {
         "name":"Company",
         "description":"Company object",
         "createdAt":"2015-05-11T17:11:32Z",
         "updatedAt":"2015-05-11T17:11:32Z",
         "idField":"id",
         "dedupeFields":[
            "externalCompanyId"
         ],
         "searchableFields":[
            [
               "externalCompanyId"
            ],
            [
               "id"
            ],
            [
               "company"
            ]
         ],
         "fields":[
            {
               "name":"createdAt",
               "displayName":"Created At",
               "dataType":"datetime",
               "updateable":false
            },
            {
               "name":"externalCompanyId",
               "displayName":"External Company Id",
               "dataType":"string",
               "length":100,
               "updateable":false
            },
            {
               "name":"id",
               "displayName":"Id",
               "dataType":"integer",
               "updateable":false
            },
            {
               "name":"updatedAt",
               "displayName":"Updated At",
               "dataType":"datetime",
               "updateable":false
            },
            {
               "name":"annualRevenue",
               "displayName":"Annual Revenue",
               "dataType":"currency",
               "updateable":true
            }
            {
               "name":"company",
               "displayName":"Company Name",
               "dataType":"string",
               "length":255,
               "updateable":true
            }
         ]
      }
   ]
}

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
GET /rest/v1/companies.json?filterType=id&filterValues=3433,5345

{
   "requestId":"e42b#14272d07d78",
   "success":true,
   "result":[
      {
         "seq":0,
         "id":3433,
         "externalCompanyId":"19UYA31581L000000",
         "company":"Google"
      },
      {
         "seq":1,
         "id":5345,
         "externalCompanyId":"29UYA31581L000000",
         "company":"Yahoo"
      }
   ]
}

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.

POST /rest/v1/companies.json

Content-Type: application/json

{
   "action":"createOrUpdate",
   "dedupeBy":"dedupeFields",
   "input":[
      {
         "externalCompanyId":"19UYA31581L000000",
         "company":"Google"
      },
      {
         "externalCompanyId":"29UYA31581L000000",
         "company":"Yahoo"
      }
   ]
}

{
   "requestId":"e42b#14272d07d78",
   "success":true,
   "result":[
      {
         "seq":0,
         "status":"updated",
         "id":1232
      },
      {
         "seq":1,
         "status":"created",
         "id":1323
      }
   ]
}

Fields

The company object contains a set of fields. Each field definition is composed 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.

GET /rest/v1/companies/schema/fields/industry.json

{
    "requestId": "88f6#17e976d6ab4",
    "result": [
        {
            "displayName": "Industry",
            "name": "industry",
            "description": null,
            "dataType": "string",
            "length": 255,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        }
    ],
    "success": true
}

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.

GET /rest/v1/companies/schema/fields.json?batchSize=5

{
    "requestId": "b50e#17e995c2d35",
    "result": [
        {
            "displayName": "Company Name",
            "name": "company",
            "description": null,
            "dataType": "string",
            "length": 255,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        },
        {
            "displayName": "Site",
            "name": "site",
            "description": null,
            "dataType": "string",
            "length": 255,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        },
        {
            "displayName": "Website",
            "name": "website",
            "description": null,
            "dataType": "url",
            "length": 255,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        },
        {
            "displayName": "Main Phone",
            "name": "mainPhone",
            "description": null,
            "dataType": "string",
            "length": 255,
            "isHidden": false,
            "isHtmlEncodingInEmail": true,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        },
        {
            "displayName": "Annual Revenue",
            "name": "annualRevenue",
            "description": null,
            "dataType": "currency",
            "isHidden": false,
            "isHtmlEncodingInEmail": false,
            "isSensitive": false,
            "isCustom": false,
            "isApiCreated": false
        }
    ],
    "success": true,
    "nextPageToken": "L7XD3EFJ3OLFZKXKJBWYULOTRA======",
    "moreResult": true
}

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.

Content-Type: application/json

POST /rest/v1/companies/delete.json

{
   "deleteBy":"dedupeFields",
   "input":[
      {
         "externalCompanyId":"19UYA31581L000000"
      },
      {
         "externalCompanyId":"29UYA31581L000000"
      },
      {
         "externalCompanyId":"39UYA31581L000000"
      }
   ]
}

{
   "requestId":"e42b#14272d07d78",
   "success":true,
   "result":[
      {
         "seq":0,
         "id":1234,
         "status":"deleted"
      },
      {
         "seq":1,
         "id":56456,
         "status":"deleted"
      },
      {
         "seq":2,
         "status":"skipped",
         "reasons":[
            {
               "code":"1013",
               "message":"Record not found"
            }
         ]
      }
   ]
}

Timeouts

  • Companies endpoints have a timeout of 30s unless noted below

    • Sync Companies: 60s
    • Delete Companies: 60s
Previous pageActivities
Next pageCustom Objects

Marketo Engage


Marketo Migration to the Adobe Admin Console - (Pre-Migration)

Experience Cloud Tech Sessions

Tuesday, Mar 4, 6:00 PM UTC

Join Adobe's Customer Experience and Identity Team to prepare for a smooth Marketo migration to the Adobe Admin Console. Learn key steps, best practices, and how to avoid roadblocks for a seamless transition.

Register

Marketo Migration to the Adobe Admin Console - (Post-Migration)

Experience Cloud Tech Sessions

Tuesday, Mar 11, 4:00 PM UTC

Migrated Marketo to the Adobe Admin Console? Join our webinar to master key features, best practices, and troubleshooting tips. Learn how to manage users,, settings, and more. register now!

Register

Connect with Experience League at Summit!

Get front-row access to top sessions, hands-on activities, and networking—wherever you are!

Learn more

Register now