API Reference / Companies

PUT /companies/{company_id}

Update a specific company

Note: when updating a company field, either the `id` or `name` and the `value` must be present.

Path parameters

Name Type Description
company_id req string Company ID

Request body

  • namestring

    Name of the company

  • descriptionstring

    Description of the company

  • urlstring

    URL of the company

  • phonestring

    Phone number of the company

  • addressobject

    The company's postal address.

    object fields →
    • addressstring

      Property name/number and street name

    • citystring

      Name of the city

    • statestring

      Name of the state

    • zip_codestring

      Zip code

    • country_codestring

      ISO-3166 country code

  • company_fieldsarray<object>

    Extra user-configurable data fields for Companies. Only editable by admins.

    array item fields →
    • company_fieldobject
      object fields →
      • idstringbson-id

        ID of the company field

    • valuestring

      Value for the company field

Responses

200 OK
  • statusintegerint32

    Response code

  • messagestring

    Response message

  • timestampintegerunix-timestamp

    Response time

  • dataobject
    object fields →
    • companyobject

      Referred to as 'organizations' in the web application. Companies are logical collections of Contacts and related sub-resources e.g. Deals, Actions and some basic info on the org. e.g. postal address, website. A Company may not be created directly or exist without a Contact.

      object fields →
      • idstringbson-id

        ID of the company

      • imagestring

        Base64 encoded binary image

      • namestringrequired

        Name of the company

      • descriptionstring

        Description of the company

      • phonestring

        Phone number of the company

      • photo_urlstring

        URL to company logo

      • urlstring

        URL of the company

      • addressobject

        The company's postal address.

        object fields →
        • addressstring

          Property name/number and street name

        • citystring

          Name of the city

        • statestring

          Name of the state

        • zip_codestring

          Zip code

        • country_codestring

          ISO-3166 country code

      • company_fieldsarray<object>

        Custom field values on the company.

        array item fields →
        • company_fieldobject

          Extra user-configurable data fields for Companies. Only editable by admins.

          object fields →
          • idstringbson-id

            ID of the company field

          • namestringrequired

            Name of the company field

          • typestringrequired

            Type of the company field. There are several types of custom fields that may store data in different formats. External ID type is a special type introduced for referencing entities in the external systems. Its value is unique amid the whole system. Section divider type is introduced just for visual purpose: it allows grouping custom fields. If custom fields in the section don't have values then they are hidden in the 'view' UI (but always shown in 'edit' UI). This logic is applied in the API: if a company doesn't have values for all the custom fields in the section then this section divider custom field isn't exposed in the API (along with other custom fields inside the section).

            enum: date · multi_line_text · multiple_choice · number · select_box · single_line_text · external_id · section_divider

          • positionintegerint32

            The position of the company field in the list

          • choicesarray<string>

            A list of possible choices (for fields of type `multiple_choice` or `select_box`)

        • valuestring

          Value for the company field

      • syncing_statusboolean

        Should all contacts in this company share the same status?

      • synced_status_idstringbson-id

        ID of the status, that all contacts within this company are synced to

      • syncing_tagsboolean

        Should all contacts in this company share the same tags?

      • synced_tagsarray<string>

        Tags that all contacts within this company share

      • contacts_countintegerint32

        Number of contacts in this company

      • won_deals_countintegerint32

        Number of deals closed with contacts in this company

      • total_won_amountnumber

        The total value of the won deals with contacts in this company

      • pending_deals_countintegerint32

        Number of the pending deals with contacts in this company

      • total_pending_amountnumber

        The total value of the pending deals with contacts in this company

      • contactsarray<object>

        List of contacts in the comapny

        array item fields →
        • contactobject

          Information about the people you are actively trying to sell to, and related sub-resources like Actions, Deals, Notes, Calls and Meetings.

          object fields →
          • idstringbson-id

            ID of the contact

          • titlestring

            The title of the contact

            enum: Mr · Mrs · Ms

          • first_namestring

            First name of the contact

          • last_namestring

            Last name of the contact

          • job_titlestring

            Job title of the contact

          • starredboolean

            Is the contact starred?

          • photo_urlstring

            URL of the contact's photo

          • company_idstringbson-id

            ID of the company, to which the contact belongs

          • company_namestring

            Name of the company, to whom the contact belongs

          • urlsarray<object>

            URLs associated with the contact

            array item fields →
            • typestring

              The type of URL

              enum: website · blog · twitter · linkedin · xing · facebook · google_plus · other

            • valuestring

              The URL associated with the contact

          • phonesarray<object>

            Phone numbers associated with the contact

            array item fields →
            • typestring

              The type of phone number

              enum: work · mobile · home · direct · fax · company · other

            • valuestring

              The phone number associated with the contact

          • emailsarray<object>

            Email addresses associated with the contact

            array item fields →
            • typestring

              The type of email address

              enum: work · home · other

            • valuestring

              The email address associated with the contact

          • address_listarray<object>

            An array of contact addresses.

            array item fields →
            • addressstring

              Street address.

            • citystring

              City.

            • statestring

              State, province or region.

            • zip_codestring

              Postal or ZIP code.

            • country_codestring

              ISO 3166 country code, upper-case.

            • typestring

              Type of the address

              enum: work · home · billing · delivery · other

          • statusstring

            Status of the contact

          • status_idstringbson-id

            ID of the status of the contact

          • tagsarray<string>

            Tags on the contact — free-form strings from the account's tag list.

          • lead_source_idstring

            ID of the lead source of the contact

          • lead_sourcestring

            Display name of the lead source of the contact

          • backgroundstring

            Background infomation about the contact

          • owner_idstringbson-id

            ID of the user, to whom the contact belongs. Defaults to the logged API user's ID.

          • custom_fieldsarray<object>

            Custom field values on the contact, as custom field and value pairs.

            array item fields →
            • custom_fieldobject

              Extra user-configurable data fields for Contacts. Only editable by admins.

              object fields →
              • idstringbson-id

                ID of the custom field

              • namestringrequired

                Name of the custom field

              • typestringrequired

                Type of the custom field. There are several types of custom fields that may store data in different formats. External ID type is a special type introduced for referencing entities in the external systems. Its value is unique amid the whole system. Section divider type is introduced just for visual purpose: it allows grouping custom fields. If custom fields in the section don't have values then they are hidden in the 'view' UI (but always shown in 'edit' UI). This logic is applied in the API: if a contact doesn't have values for all the custom fields in the section then this section divider custom field isn't exposed in the API (along with other custom fields inside the section).

                enum: anniversary · date · multi_line_text · multiple_choice · number · select_box · single_line_text · external_id · section_divider

              • positionintegerint32

                The position of the custom field in the list

              • choicesarray<string>

                A list of possible choices (for fields of type `multiple_choice` or `select_box`)

            • valuestring

              Value for the custom field

          • letterstring

            The first letter of the contacts last name

          • pending_dealboolean

            Does the contact have one or more pending deals?

          • total_pendingsnumber

            The total value of all pending deals for the contact

          • total_deals_countintegerint32

            Number of deals associated with the contact

          • company_sizeintegerint32

            Number of contacts within the contact's company

          • sales_closed_forarray<string>

            A list of user IDs, for whom the sales cycle is closed

          • closed_salesarray<object>

            A list of closed sales objects

            array item fields →
            • user_idstringbson-id

              ID of the user, for whom the sales cycle is closed

            • closed_atintegerunix-timestamp

              Time that the sales cycle was closed

            • commentstring

              An optional message detailing why the sales cycle was closed

          • google_contacts_dataobject

            The google contacts data associated with this contact

            object fields →
            • account_emailstring

              Google contacts email

            • idstring

              Google contact id

            • saved_atintegerunix-timestamp

              Time the contact was saved to google

          • created_atstringdate-time

            Creation time of the contact

          • modified_atstringdate-time

            Last modification time of the contact

        • next_actionsarray<object>
          array item fields →
          • idstringbson-id

            ID of the action

          • assignee_idstringbson-idrequired

            ID of the user, to whom the action is assigned. Defaults to the logged API user's ID.

          • contact_idstringbson-idrequired

            ID of the contact, with whom the action is associated

          • textstringrequired

            The main text/description of the action

          • statusstring

            Status of the action

            enum: asap · date · date_time · waiting · queued · queued_with_date · done

          • datestringdate

            Due date for the action (status must be one of `date`, `date_time` or `queued_with_date`). Defaults to today's date.

          • exact_timeintegerunix-timestamp

            The UNIX Epoch time in seconds the action is due (status must be `date_time`)

          • positionintegerint32

            The position of the action (in the list of queued actions)

          • doneboolean

            Has the action been marked as complete?

          • done_atstringdate

            The date the action was completed (only returned, if action complete)

          • created_atstringdate-time

            Creation time of the action

          • modified_atstringdate-time

            Last modification time of the action

        • next_actionobject

          Completable tasks related to Contacts. ASAP first, then dated actions ordered by due date (overdue first), followed by waiting for (blocked) and finally queued actions (without any date).

          object fields →
          • idstringbson-id

            ID of the action

          • assignee_idstringbson-idrequired

            ID of the user, to whom the action is assigned. Defaults to the logged API user's ID.

          • contact_idstringbson-idrequired

            ID of the contact, with whom the action is associated

          • textstringrequired

            The main text/description of the action

          • statusstring

            Status of the action

            enum: asap · date · date_time · waiting · queued · queued_with_date · done

          • datestringdate

            Due date for the action (status must be one of `date`, `date_time` or `queued_with_date`). Defaults to today's date.

          • exact_timeintegerunix-timestamp

            The UNIX Epoch time in seconds the action is due (status must be `date_time`)

          • positionintegerint32

            The position of the action (in the list of queued actions)

          • doneboolean

            Has the action been marked as complete?

          • done_atstringdate

            The date the action was completed (only returned, if action complete)

          • created_atstringdate-time

            Creation time of the action

          • modified_atstringdate-time

            Last modification time of the action

        • queued_actionsarray<object>
          array item fields →
          • idstringbson-id

            ID of the action

          • assignee_idstringbson-idrequired

            ID of the user, to whom the action is assigned. Defaults to the logged API user's ID.

          • contact_idstringbson-idrequired

            ID of the contact, with whom the action is associated

          • textstringrequired

            The main text/description of the action

          • statusstring

            Status of the action

            enum: asap · date · date_time · waiting · queued · queued_with_date · done

          • datestringdate

            Due date for the action (status must be one of `date`, `date_time` or `queued_with_date`). Defaults to today's date.

          • exact_timeintegerunix-timestamp

            The UNIX Epoch time in seconds the action is due (status must be `date_time`)

          • positionintegerint32

            The position of the action (in the list of queued actions)

          • doneboolean

            Has the action been marked as complete?

          • done_atstringdate

            The date the action was completed (only returned, if action complete)

          • created_atstringdate-time

            Creation time of the action

          • modified_atstringdate-time

            Last modification time of the action

        • next_action_conflictsarray<any>
      • pending_dealsarray<object>

        Pending deals across the company's contacts.

        array item fields →
        • dealobject

          Represent (potential) financial transactions with your contacts. Deals include information like amount, deal stage, closed date or expected close date. Deals support file attachments.

          object fields →
          • idstringbson-id

            ID of the deal

          • contact_idstringbson-idrequired

            ID of the contact, to whom the deal belongs

          • owner_idstringbson-idrequired

            ID of the user, to whom the deal belongs. Defaults to the logged API user's ID.

          • pipeline_idstringbson-id

            ID of a pipeline the deal belongs to

          • sales_pipeline_idstringbson-id

            ID of a sales pipeline the deal belongs to

          • namestringrequired

            Name of the deal

          • textstring

            Extra notes related to the deal (supports `[b]bold[/b]` and `[i]italic[/i]` formatting)

          • stageintegerint32

            A numerical representation of the progress of a pending deal (number ranging from 0 to 100 exclusive)

          • statusstring

            Status of the deal

            enum: pending · won · lost

          • expected_close_datestringdate

            The date the deal is expected to close (status should be `pending`). Defaults to today's date.

          • close_datestringdate

            The date the deal actually closed (status should be `won` or `lost`). Defaults to today's date.

          • datestringdate

            Creation date of the deal. Defaults to today's date.

          • amountnumberfloat

            The monitary value of the deal (per month, if multi-month deal)

          • monthsintegerint32

            Number of months the deal is to be paid for (1 for regular deals, 2+ for multi-month)

          • costnumberfloat

            The monitary cost of the deal

          • marginnumberfloat

            Profit margin for the deal (`amount` minus `cost`)

          • total_amountnumberfloat

            Product of amount and months (will only differ from `amount` field, if multi-month deal)

          • total_costnumberfloat

            Product of cost and months (will only differ from `cost` field, if multi-month deal)

          • commission_basestring

            Base used to calculate the commission of the deal

            enum: amount · margin

          • commission_typestring

            Type of commission for the deal

            enum: none · percentage · absolute

          • commissionnumberfloat

            Commission payable for the deal

          • commission_percentagenumberfloat

            Commission percentage for the deal

          • reason_lost_idstringbson-id

            ID of the reason lost

          • deal_fieldsarray<object>

            Custom field values on the deal.

            array item fields →
            • deal_fieldobject

              Extra user-configurable data fields for Deals. Only editable by admins.

              object fields →
              • idstringbson-id

                ID of the deal field

              • namestringrequired

                Name of the deal field

              • typestringrequired

                Type of the deal field. There are several types of custom fields that may store data in different formats. External ID type is a special type introduced for referencing entities in the external systems. Its value is unique amid the whole system. Section divider type is introduced just for visual purpose: it allows grouping custom fields. If custom fields in the section don't have values then they are hidden in the 'view' UI (but always shown in 'edit' UI). This logic is applied in the API: if a deal doesn't have values for all the custom fields in the section then this section divider custom field isn't exposed in the API (along with other custom fields inside the section).

                enum: date · multi_line_text · multiple_choice · number · select_box · single_line_text · external_id · section_divider

              • positionintegerint32

                The position of the deal field in the list

              • choicesarray<string>

                A list of possible choices (for fields of type `multiple_choice` or `select_box`)

            • valuestring

              Value for the deal field

          • has_deal_itemsboolean

            Does the deal have deal items?

          • deal_itemsarray<object>

            Line items on the deal — each with a name, quantity, price, cost and amount.

            array item fields →
            • idstringbson-id

              ID of the deal item

            • namestringrequired

              Name of the deal item

            • descriptionstringrequired

              Description text of the deal item

            • costnumberfloatrequired

              Cost of the deal item

            • pricenumberfloatrequired

              Price of the deal item

            • amountnumberfloat

              Amount of the deal items

            • qtyintegerint32required

              Quantity of deal items

            • deal_idstringbson-id

              ID of the parent deal

            • predefined_item_idstringbson-id

              ID of the predefined item used for deal item creation (can be empty)

            • positionintegerint32

              Position of the predefined item in the items list

            • created_atstringdate-time

              Creation time of the deal item

            • modified_atstringdate-time

              Last modification time of the deal item

          • authorstring

            Shortened name of the creator of the deal. Defaults to the logged API user.

          • has_related_notesboolean

            Does the deal have related notes?

          • attachmentsarray<object>

            Files attached to the deal.

            array item fields →
            • idstringbson-id

              ID of the attachment

            • filenamestringrequired

              Name of the attachment file

            • custom_filenamestring

              Custom name of the attachment file

            • pinnedboolean

              Show if the attachment is pinned to its owner contact

            • pinned_atstring

              Shows pinned at timestamp. Is null if pinned == false

            • sizeintegerint32required

              Size of the attachment file (in bytes)

            • storage_providerstring

              Name of the storage provider (where the attachment file is stored)

              enum: amazon · google_drive · dropbox · evernote

            • urlstring

              External URL of the attachment file

            • url_expires_atstringdate-time

              The time the attachment URL expires

            • thumbnailobject

              An image preview of the attachment file (if one exists)

              object fields →
              • urlstring

                External URL of the attachment's thumbnail

          • contact_infoobject

            Information about the contact, to whom the deal belongs (read only).

            object fields →
            • contact_namestring

              Name of the contact associated with the deal

            • companystring

              Name of the company associated with the deal

          • ownerobject

            Information about the deal owner (read only).

            object fields →
            • idstring

              ID of the deal owner

            • namestring

              Name of the deal owner

            • emailstring

              Email address of the deal owner

          • previous_pipeline_stagesobject

            Returns the last stage in which the deal was for each pipeline (pipeline_id => stage) This field is returned only when 'include_history=true' param is supplied in query string

          • created_atstringdate-time

            Creation time of the deal

          • modified_atstringdate-time

            Last modification time of the deal

          • linked_contactsarray<object>

            Short form of contacts linked to the deal. Always returned with the deal payload (on both `GET /deals` and `GET /deals/{deal_id}`). For full contact objects use `fields=contacts(all)` on `GET /deals`.

            array item fields →
            • idstringbson-id

              ID of the linked contact

            • contact_namestring

              Full display name of the linked contact

            • companystring

              Display name of the company the contact belongs to (empty string if none)

            • photo_urlstring

              URL of the contact's profile picture (empty string if none)

      • created_atstringdate-time

        Creation time of the company

      • modified_atstringdate-time

        Last modification time of the company

Standard error responses: 400 · 401 · 403 · 404 · 409 · 500 — shared across the API. See Errors.

Related guides