Companies

  • Return all of the user's companies

    GET /api/1/companies.json
    Formats
    json jsonp

    Returns an array of company objects belonging to the authenticated user Can take a URL-encoded, SQL-like query string and order string which can help filter and order the results that will be returned. So the query string:

    name ~= "quia+itaque"

    which lookes like this when URL encoded:

    /api/1/companies.json?where=name~%3D"quia+itaque"&order=name+asc

    will return all companies similar to “quia itaque” ordered by name in ascending order.

    Click here for more information on the API query string.

    Errors
    • 401 Unauthorized
    • 403 Read Denied - if the user is not allowed to read companies
    Example
    GET /api/1/companies
    200
    {
      "response": [
        {
          "contact_email_address": null,
          "contact_first_name": null,
          "contact_home_phone": null,
          "contact_last_name": null,
          "contact_mobile_phone": null,
          "contact_position": null,
          "contact_salutation": null,
          "fax_phone": null,
          "latitude": null,
          "longitude": null,
          "main_address": null,
          "main_city": null,
          "main_country": null,
          "main_phone": null,
          "main_postcode": null,
          "main_state": null,
          "name": "Durgan and Sons",
          "notes": null,
          "uuid": "16de762d-3ac9-4a87-8629-2c0550d6b585",
          "visibility": "private",
          "website": null,
          "user_uuids": [
            "1a7f0cae-3f49-4242-bbf7-f70574d8bcb5"
          ]
        },
        {
          "contact_email_address": null,
          "contact_first_name": null,
          "contact_home_phone": null,
          "contact_last_name": null,
          "contact_mobile_phone": null,
          "contact_position": null,
          "contact_salutation": null,
          "fax_phone": null,
          "latitude": null,
          "longitude": null,
          "main_address": null,
          "main_city": null,
          "main_country": null,
          "main_phone": null,
          "main_postcode": null,
          "main_state": null,
          "name": "Johnston, Hessel and Hermiston",
          "notes": null,
          "uuid": "50782442-0171-41a1-b9a7-85830d379725",
          "visibility": "private",
          "website": null,
          "user_uuids": [
            "1a7f0cae-3f49-4242-bbf7-f70574d8bcb5"
          ]
        },
        {
          "contact_email_address": null,
          "contact_first_name": null,
          "contact_home_phone": null,
          "contact_last_name": null,
          "contact_mobile_phone": null,
          "contact_position": null,
          "contact_salutation": null,
          "fax_phone": null,
          "latitude": null,
          "longitude": null,
          "main_address": null,
          "main_city": null,
          "main_country": null,
          "main_phone": null,
          "main_postcode": null,
          "main_state": null,
          "name": "Schumm LLC",
          "notes": null,
          "uuid": "3d0f1406-4768-401b-ae3f-0868f608936b",
          "visibility": "private",
          "website": null,
          "user_uuids": [
            "1a7f0cae-3f49-4242-bbf7-f70574d8bcb5"
          ]
        }
      ],
      "count": 3
    }
    Parameters
    • where

      An SQL-like query string which can filter the results that will be returned

    • order

      An SQL-like order string, that sets the order of the returned objects

  • Return a single company

    GET /api/1/companies/:uuid.json
    Formats
    json jsonp

    Returns a single company object belonging to the authenticated user.

    Errors
    • 401 Unauthorized
    • 403 Read Denied - if the user is not allowed to read this company
    • 404 Record Not Found - returned if a company with the specified UUID is not found
    Example
    GET /api/1/companies/ad3bc392-e5ec-4b7c-b6d7-90880f50a80d
    200
    {
      "response": {
        "contact_email_address": null,
        "contact_first_name": null,
        "contact_home_phone": null,
        "contact_last_name": null,
        "contact_mobile_phone": null,
        "contact_position": null,
        "contact_salutation": null,
        "fax_phone": null,
        "latitude": null,
        "longitude": null,
        "main_address": null,
        "main_city": null,
        "main_country": null,
        "main_phone": null,
        "main_postcode": null,
        "main_state": null,
        "name": "Lakin-Little",
        "notes": null,
        "uuid": "ad3bc392-e5ec-4b7c-b6d7-90880f50a80d",
        "visibility": "private",
        "website": null,
        "user_uuids": [
          "b5075fab-e735-41c9-bd1f-f090b9c475e1"
        ]
      }
    }
  • Create a new company

    POST /api/1/companies.json
    Formats
    json jsonp

    Creates a new company. Requires a valid company object to be posted.

    Errors
    • 401 Unauthorized
    • 403 Create Denied - if the user is not allowed to create a company
    • 422 Invalid Record - if the company fails validation. An error message will be returned, declaring the error.
    Example
    POST /api/1/companies
    {
      "company": {
        "name": "Deckow, Trantow and Weimann"
      }
    }
    200
    {
      "response": {
        "contact_email_address": null,
        "contact_first_name": null,
        "contact_home_phone": null,
        "contact_last_name": null,
        "contact_mobile_phone": null,
        "contact_position": null,
        "contact_salutation": null,
        "fax_phone": null,
        "latitude": null,
        "longitude": null,
        "main_address": null,
        "main_city": null,
        "main_country": null,
        "main_phone": null,
        "main_postcode": null,
        "main_state": null,
        "name": "Deckow, Trantow and Weimann",
        "notes": null,
        "uuid": "c3997a19-d43f-4ea5-aef8-6626a13d5bec",
        "visibility": "private",
        "website": null,
        "user_uuids": [
          "a51dec63-b632-4521-944a-8bba893fa812"
        ]
      }
    }
    Parameters
    • company

      An company JSON object.

      • uuid

        A UUID to identify the company. If null, one will be generated

      • name

        Name of the company

      • visibility

        Sets the visibility of the company. Public companies will be added to all staff; Private companies will only be available to the owner; Custom companies are only available to users in the user_uuids array

      • contact_salutation

        Salutation of the contact at the company

      • contact_first_name

        First name of the contact at the company

      • contact_last_name

        Last name of the contact at the company

      • contact_email_address

        Email address of the contact at the company

      • contact_position

        The position of the contact at the company

      • contact_home_phone

        Home phone number of the contact at the company

      • contact_mobile_phone

        Mobile phone number of the contact at the company

      • website

        Web address of the company

      • main_phone

        Phone number of the company

      • fax_phone

        Fax number of the company

      • main_address

        Street address of the company

      • main_city

        City the company resides in

      • main_state

        State the company resides in

      • main_postcode

        Postcode of the company

      • main_country

        Country the company resides in

      • notes

        Notes associated with the company

      • user_uuids

        Array of User UUIDs that can see the company. Requires visibility to be set to ‘custom’

      • longitude

        Longitude of the company. If blank, we’ll try to guess from the address (Requires all address fields to be complete).

      • latitude

        Latitude of the company. If blank, we’ll try to guess from the address (Requires all address fields to be complete).s

  • Update a company

    PUT /api/1/companies/:uuid.json
    Formats
    json jsonp

    Update an existing company. Requires a valid company object to be posted. Missing attributes from the object will be merged with the existing company.

    Errors
    • 401 Unauthorized
    • 403 Update Denied - if the user is not allowed to update this company
    • 404 Record Not Found - returned if an company with the specified UUID is not found
    • 422 Invalid Record - if the company fails validation. An error message will be returned, declaring the error.
    Example
    PUT /api/1/companies/2226923c-f1f4-428b-8667-3a08999ccc44
    {
      "company": {
        "name": "Kautzer, Skiles and Hills"
      }
    }
    200
    Parameters
    • company

      An company JSON object.

      • uuid

        A UUID to identify the company. If null, one will be generated

      • name

        Name of the company

      • visibility

        Sets the visibility of the company. Public companies will be added to all staff; Private companies will only be available to the owner; Custom companies are only available to users in the user_uuids array

      • contact_salutation

        Salutation of the contact at the company

      • contact_first_name

        First name of the contact at the company

      • contact_last_name

        Last name of the contact at the company

      • contact_email_address

        Email address of the contact at the company

      • contact_position

        The position of the contact at the company

      • contact_home_phone

        Home phone number of the contact at the company

      • contact_mobile_phone

        Mobile phone number of the contact at the company

      • website

        Web address of the company

      • main_phone

        Phone number of the company

      • fax_phone

        Fax number of the company

      • main_address

        Street address of the company

      • main_city

        City the company resides in

      • main_state

        State the company resides in

      • main_postcode

        Postcode of the company

      • main_country

        Country the company resides in

      • notes

        Notes associated with the company

      • user_uuids

        Array of User UUIDs that can see the company. Requires visibility to be set to ‘custom’

      • longitude

        Longitude of the company. If blank, we’ll try to guess from the address (Requires all address fields to be complete).

      • latitude

        Latitude of the company. If blank, we’ll try to guess from the address (Requires all address fields to be complete).s

  • Delete a company

    DELETE /api/1/companies/:uuid.json
    Formats
    json jsonp

    Deletes the company associated with the supplied uuid

    Errors
    • 401 Unauthorized
    • 403 Update Denied - if the user is not allowed to delete this company
    • 404 Record Not Found - returned if an company with the specified UUID is not found
    Example
    DELETE /api/1/companies/fc3a2e4e-2794-4fec-90a0-31131fdc58ba
    200