GET /companies

Get a list of companies

Returns the account's companies, sorted by name.

Query parameters

Name	Type	Description
`name`	string	Search companies by name
`phone`	string	Search companies by phone number
`letter`	string	Return company whose name begins with specified letter
`sort_by`	string	Specify field by which to order the results (use in conjunction with `order`)
`order`	string	Specify the order (ascending or descending) of the sort of the results (use in conjunction with `sort_by`)
`page`	integer	Page number. Starts from 1. Default is 1.
`per_page`	integer	Number of records to return. Maximum 100 allowed. Default is 10.

Responses

200 OK

statusintegerint32
Response code
messagestring
Response message
timestampintegerunix-timestamp
Response time
dataobject
object fields →
- companiesarray<object>
  array item 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
- total_countintegerint32
  Total number of items
- pageintegerint32
  Current page number
- per_pageintegerint32
  Number of items returned in each page
- max_pageintegerint32
  The page number of the last page of items

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

Related guides

GET /companies

curl "https://app.onepagecrm.com/api/v3/companies" \
  -u $user_id:$api_key

200 example response

{
  "status": 0,
  "message": "OK",
  "timestamp": 1528373119,
  "data": {
    "companies": [
      {
        "company": {
          "id": "5aba31e99007ba0f570c92ac",
          "image": "data:image/png;base64,iVBORw...",
          "name": "Crockett & Tubbs Security",
          "description": "For all your security needs",
          "phone": "(912) 644-1771",
          "photo_url": "https://example.com/someimage.png",
          "url": "https://{foo.bar}",
          "address": {
            "address": "Unit 5, Business Innovation Centre",
            "city": "Upper Newcastle",
            "state": "Galway",
            "zip_code": "H91 Y0T0",
            "country_code": "IE"
          },
          "company_fields": [
            {}
          ],
          "syncing_status": true,
          "synced_status_id": "5aaa9b039007ba08c9ebaf0a",
          "syncing_tags": true,
          "synced_tags": [
            "Java",
            "Android",
            "iOS"
          ],
          "contacts_count": 3,
          "won_deals_count": 5,
          "total_won_amount": 999.99,
          "pending_deals_count": 1,
          "total_pending_amount": 99.99,
          "contacts": [
            {}
          ],
          "pending_deals": [
            {}
          ],
          "created_at": "2018-05-16T11:52:09Z",
          "modified_at": "2018-05-16T11:52:09Z"
        }
      }
    ],
    "total_count": 1,
    "page": 1,
    "per_page": 10,
    "max_page": 1
  }
}