Get All Companies

This GET endpoint retrieves a list of all companies.

Endpoint

• URL: /api/companies
• Method: GET

Authentication

• Header: accessToken
• Type: Bearer Token
• Value: <ACCESS-TOKEN>

Request Headers

Header	Type	Description
accessToken	string	Access token for authentication. (required)

Query Parameters

Parameter	Type	Description
page	number	The page number to retrieve. Defaults to 1 if not specified.
limit	number	The maximum number of items to return per page. Defaults to 10 if not specified.
name	string	Filter for company name using a regular expression. Supports partial matches with case insensitivity.
email	string	Filter for company email using a regular expression. Supports partial matches with case insensitivity.
status	string	Filter by the company's status.
id	string	Filter for a specific company by its unique ID.
id:in	string	Filter for multiple companies by a comma-separated list of IDs.
date_created:min	string	Filters companies created on or after the specified date. Date should be in ISO 8601 format.
date_created:max	string	Filters companies created on or before the specified date. Date should be in ISO 8601 format.
date_modified:min	string	Filters companies modified on or after the specified date. Date should be in ISO 8601 format.
date_modified:max	string	Filters companies modified on or before the specified date. Date should be in ISO 8601 format.
metafields	string	Used to filter by specific metafield value. Typically in the format metafields:field_name=value.
metafields-in	string	Used to filter by specific metafield values included in a list. Typically in the format metafields-in:field_name=val1,val2.

Sample Request

curl --location '<BASE-URL>/companies' \
--header 'accessToken: <ACCESS-TOKEN>'

Response

• Status Code: 200 OK

Sample Response Body

The response will include a list of companies with their details.

{
  "success": true,
  "data": [
    {
      "id": "company_id_1",
      "name": "Company Name 1",
      "address": "Company Address"
      // additional fields...
    },
    {
      "id": "company_id_2",
      "name": "Company Name 2",
      "address": "Company Address"
      // additional fields...
    }
    // More companies...
  ]
}

Success Response Body

When successfully retrieving companies, the response will contain details for each company. Here's a breakdown of the response body:

Field	Type	Description
success	boolean	Indicates whether the request was successful.
data	array	An array of company objects containing detailed information about each company.
pagination	object	Pagination details for navigating large sets of data.

Company Object Structure

Each company within the data array contains:

Field	Type	Description
id	string	ID of the company.
entityId	number	Unique identifier for the company within the system.
name	string	Name of the company.
email	string	Email address associated with the company.
phoneNumber	string	Primary contact number for the company.
status	string	Current status of the company (e.g., "active").
billingAddress	array	An array of billing address objects for the company.
shippingAddress	array	An array of shipping address objects for the company.
priceLists	array	Price lists associated with the company. Currently empty in the sample response.
productGroups	object	Product group inclusion/exclusion details.
shippingMethods	array	Shipping methods available for the company.
paymentMethods	array	Payment methods available for the company.
isTaxExempt	Boolean	Does company is Tax Exempt
paymentTerms	Array	Payment Terms available for the company.
isSubCompany	boolean	Indicates whether the company is a subsidiary.
createdBy	object	Information about the user or account that created this company entry.
metaFields	array	Additional meta-information about the company. Currently empty in the sample response.
createdAt	string	Timestamp of when the company entry was created.
updatedAt	string	Timestamp of the last update to the company entry.
logo	string	URL of the company's logo, if available.
notes	string	Additional notes about the company.
companyGroup	any	The company group to which this company belongs, if applicable.

Billing/Shipping Address Structure

Each address (billing and shipping) contains:

Field	Type	Description
id	string	Database identifier for the address.
companyName	string	Company name of this contact.
companyEmail	string	Company email of the contact.
firstName	string	First name of the contact person at this address.
lastName	string	Last name of the contact person at this address.
address1	string	Primary address line.
address2	string	Secondary address line. Optional.
phoneNumber	string	Contact phone number for the address.
city	string	City of the address.
state	object	State object containing the name and code of the state.
country	object	Country object containing the name and code of the country.
zipcode	string	Postal code of the address.
isDefaultAddress	boolean	Indicates whether this address is the default.
status	boolean	Status of the address. Indicates active/inactive.
metaFields	array	Meta information related to the address. Currently empty in the sample response.
createdAt	string	Timestamp of when the address was created.
updatedAt	string	Timestamp of the last update to the address.

Payment Terms

Field	Type	Description
paymentTerm	id	Id of payment Term.
depositRequired	boolean	Is deposit required for placing order
depositPercentage	number	Deposit percentage need to place order

Pagination Structure

Pagination information provided:

Field	Type	Description
page	number	The current page number in the response.
total	number	Total number of records available.
count	number	Number of records returned in the current response.

Error Responses

Status Code	Description
400	Bad Request: Invalid input data.
401	Unauthorized: Access token is invalid or missing.
500	Internal Server Error: An error occurred on the server.

Notes

• Ensure the access token is valid and active to authenticate the request successfully.
• The API may support pagination or filtering which should be included in the query if applicable.
• Date fields (date_created:min, date_created:max, date_modified:min, date_modified:max) expect dates in the ISO 8601 format, e.g., 2024-09-30T00:00:00Z.
• String filters like name and email use regular expressions, supporting partial matches and case insensitivity.
• The metafields and metafields-in filters allow complex querying based on metafield values associated with the entities.