FOREST CRM - XML Company API

This API provides the following services:

List companies
Create new company
Update (modify) one company

List companies

Request

The request format is:

https://app.forestcrm.hu/api/xml/<API KEY>/companies

Request HTTP method: GET

Request parameters:

id (optional):: exact internal id of the company to be returned. Only exact matches are returned. Takes precedence over all other parameters.
external_ref: If present (with any value or without value), `id` is interpreted as an external reference ("external id").
query (optional):: string to query in company data (name, address, description). Partial matches are also returned. Search is case insensitive. query string may be but does not have to be surrounded by either single or double quotation marks.
withOpportunity (optional):: return companies with opportunities only.
withContract (optional):: return companies with contracts only.

If no parameters are supplied, all companies for the tenant are returned.

Example

GET https://app.forestcrm.hu/api/xml/demo/companies?query=part&withOpportunity

GET https://app.forestcrm.hu/api/xml/demo/companies?id=A1231&external_ref

Response

Response conforms the attached XSD.

Notes:

'updated' is the last time the company's own data was updated. It does not reflect updates on contacts, activities, etc.
address_country_code elements contain ISO 3166 two-letter coutry codes

Example

<companies>
  <company id="5206">
    <updated>2010-12-29T15:44:12+01:00</updated>
    <name>Some partner</name>
    <address_city>My city</address_city>
    <address_zip>12345</address_zip>
    <address_street>2001 Main Street</address_street>
    <address_country_code>US</address_country_code>
    <salesrep>Alan Shephard</salesrep>
    <homepage>http://www.some-partner.net</homepage>
    <tax_number>123-456-A-3</tax_number>
    <description></description>
    <archive>false</archive>
    <categories>
      <category>Size: 10-50</category>
    </categories>
    <external_ref>CPY-1766</external_ref>
  </company>
  <company id="5207">
    <updated>2010-12-29T08:37:38+01:00</updated>
    <name>Another partner</name>
    <address_city>My town</address_city>
    <address_zip>24680</address_zip>
    <address_street>44 Downtown Drive</address_street>
    <address_country_code>GB</address_country_code>
    <salesrep>Mike Johnson</salesrep>
    <description>Used to be a good client</description>
    <archive>true</archive>
    <categories>
      <category>Size: 10-50</category>
      <category>VIP</category>
    </categories>
  </company>
</companies>

Create new company

Request

The request format is:

https://app.forestcrm.hu/api/xml/<API KEY>/companies

Request HTTP method: POST

Request parameters (optional params default to empty unless noted otherwise):

company["name"]:: Name of the company.
company["description"]:: Company description text. Optional.
company["salesrep_id"]:: The ID of the user (salesrep) who is responsible for the company. Can be retrieved via the User API. Optional.
company["address_street"]:: Street address. Optional.
company["address_city"]:: City address. Optional.
company["address_zip"]:: ZIP code (string). Optional.
company["address_country"]:: Country code (two letter code, see list ('territory' section)). Optional.
company["homepage"]:: Company home page. Optional.
company["email"]:: Company (central) email. Optional.
company["tax_number"]:: Tax identification id (string). Optional.
company["archive"]:: Is the company to be archived (true/false). Optional, defaults to false.
company["category_ids"]:: Array of company category IDs to associate with the company. Can be retrieved via the Category API. Invalid values omitted. Optional.
company["external_ref"]:: External reference to the entity. Optional.

Example

POST https://app.forestcrm.hu/api/xml/demo/companies

Header:

Content-Type: application/json

Body:

{
  "company": {
    "name": "Great Company",
    "salesrep_id": 2400,
    "address_street": "1 My Way",
    "address_city": "Smallville",
    "address_country": "AD",
    "tax_number": "A23445/2011",
    "category_ids": [2145, 2210]
  }
}

Response

If the company could be created the response is of status code 200 and the body contains the the ID of the company created in XML format:

  <company>
    <id type="integer">14914</id>
  </company>

Errors are reported with a status code (422) and the response body contains the errors in XML format.

Update (modify) an existing company

Request

The request format is:

https://app.forestcrm.hu/api/xml/<API KEY>/companies/<company ID>

https://app.forestcrm.hu/api/xml/<API KEY>/companies/<company ID>?external_ref

external_ref: If present (with any value or without value), `id` is interpreted as an external reference ("external id").

Request HTTP method: PUT

Request parameters: same as in create

Note that the requested attributes get updated (overwritten), missing attributes don't change.

Example

PUT https://app.forestcrm.hu/api/xml/demo/companies/14914

Header:

Content-Type: application/json

Body:

{
  "company": {
    "homepage": "http://greatcompany.example.com"
  }
}

Response

If the company could be updated the response is of status code 200.

Errors are reported with a status code (422) and the response body contains the errors in XML format.

Back to index