Arlo

REST Auth API: Organisations

Organisation resources represent a company, business or group entity within the platform. A organisation may be associated with Contacts (as an employer).

Organisations are described by a name, email, integration codes and phone numbers. In addition to this basic information, organisations have a number of linked sub-resources that describe other details such as their postal and physical addresses, key contacts, and related parent/child organisations.

This resource supports retrieval of individual organisation instances, collections of organisations (with filters), creating new organisations, and updating existing organisations.

This entity also supports CustomFields.

Merged organisations

Integrators keeping organisations synchronised with an external system should note that some records can be deleted without notice due to merges between two organisation resources. HTTP GET requests to resources moved due to a merge will return a HTTP 308 Permanent Redirect status with headers referring to the merged organisation URI and the original OrganisationMergeRequest. To keep the external system consistent, integrators should query both this resource and also the OrganisationMergeRequests resource to identify merge operations that will have moved tracked organisation records.

Organisation instance resource

Resource URI

/api/2012-02-01/auth/resources/organisations/{OrganisationID}/

Resource properties

Property Description
OrganisationID An integer value that uniquely identifies this resource within the platform. This field is read-only.
Name A string representing the name of this organisation, up to 128 characters long.
LegalName A string representing the legal name of this organisation, up to 128 characters long.
Email A string representing the email of this organisation, up to 128 characters long.
CodePrimary A string representing an internal (primary) code used to reference this organisation, up to 36 characters long. This property is useful for storing and managing identifier values from external systems.
CodeSecondary A string representing an internal (secondary) code used to reference this organisation, up to 36 characters long. This property is useful for storing and managing identifier values from external systems.
PhonePrimary A string representing the main (primary) contact phone number for this organisation, up to 32 characters long.
PhoneSecondary A string representing an alternate (secondary) contact phone number for this organisation, up to 32 characters long.
WebsiteUrl A string representing the website URL for this organisation, up to 256 characters long.
Status A OrganisationStatus value representing the current state of this organisation, such as active or inactive (archived).
CreatedDateTime A UTC DateTime value indicating when this resource was created. This field is read-only.
LastModifiedDateTime A UTC DateTime value indicating when this resource was last modified. This field is read-only.
Link (title) Description
PostalAddress Reference to an Address resource representing the postal address for this organisation.
PhysicalAddress Reference to an Address resource representing the physical address for this organisation.
AccountManager Reference to a Contact resource representing the individual managing the account for this organisation.
KeyContact Reference to a Contact resource representing the primary contact within the organisation for managing the account relationship.
ParentOrganisation Reference to an Organisation resource representing the parent owner of this organisation.
ChildOrganisations Reference to a collection of Organisation links representing child organisations owned by this organisation.

HTTP GET

Returns a representation of an Organisation, including the properties and links above.

Optional parameters
Parameter Description
expand Expression referencing Link elements to expand when generating the response. See link expansion.
Response

See HTTP response status codes for a general overview of all possible API status codes. Common response codes for GET operations are listed below.

Status Description
200 OK Resource was successfully retrieved.
308 Permanent Redirect Organisation has been merged with another resource. HTTP response will contain two headers:
Example

GET /api/2012-02-01/auth/resources/organisations/823/

<Organisation>
  <OrganisationID>823</OrganisationID>
  <Name>Acme Consultants</Name>
  <LegalName>Acme Consultants Limited</LegalName>
  <Email>admin@acme.example.org</Email>
  <CodePrimary>ACMECONSUL04</CodePrimary>
  <CodeSecondary>74-582-821</CodeSecondary>
  <PhonePrimary>+64 4 211 2334</PhonePrimary>
  <PhoneSecondary>+64 4 211 2334 ext 231</PhoneSecondary>
  <WebsiteUrl>acme.example.org</WebsiteUrl>
  <Status>Active</Status>
  <CreatedDateTime>2009-11-23T02:49:59.493Z</CreatedDateTime>
  <LastModifiedDateTime>2009-11-25T02:11:32.174Z</LastModifiedDateTime>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PostalAddress" type="application/xml" title="PostalAddress" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/postaladdress/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/AccountManager" type="application/xml" title="AccountManager" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/32/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/KeyContact" type="application/xml" title="KeyContact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/683/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/ChildOrganisations" type="application/xml" title="ChildOrganisations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/childorganisations/"/>
</Organisation>

HTTP POST

Not supported.

HTTP PUT

Performs an update of an Organisation by replacing the entire representation with a new copy.

The submitted Organisation representation must be complete. Omitted properties will be updated to null, and omitted links (such as addresses and key contact information) will deleted if they previously existed. This operation should always be executed using a modified instance from a previous HTTP GET request.

Response

See HTTP response status codes for a general overview of all possible API status codes. Common response codes for PUT operations are listed below.

Status Description
200 OK Resource was successfully updated.
400 Bad Request HTTP request body contains malformed or invalid parameters.
409 Conflict Resource could not be updated because it contains values that conflict with those on the server.
Example 1

Simple update of an existing organisation. The operation also includes a new PostalAddress and KeyContact reference for the organisation, overwriting any previous value.

PUT https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 1769
<Organisation>
  <OrganisationID>823</OrganisationID>
  <Name>Acme Consultants</Name>
  <LegalName>Acme Consultants Limited</LegalName>
  <Email>admin@acme.example.org</Email>
  <CodePrimary>ACMECONSUL04</CodePrimary>
  <CodeSecondary>74-582-821</CodeSecondary>
  <PhonePrimary>+64 4 211 2334</PhonePrimary>
  <PhoneSecondary>+64 4 211 2334 ext 231</PhoneSecondary>
  <WebsiteUrl>acme.example.org</WebsiteUrl>
  <Status>Active</Status>
  <CreatedDateTime>2009-11-23T02:49:59.493Z</CreatedDateTime>
  <LastModifiedDateTime>2009-11-25T02:11:32.174Z</LastModifiedDateTime>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PostalAddress" type="application/xml" title="PostalAddress" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/postaladdress/">
    <Address>
      <StreetLine1>98 Wallacetown Quay</StreetLine1>
      <StreetLine2>PO Box 98442</StreetLine2>
      <SuburbOrRegion>Northcote</SuburbOrRegion>
      <City>Metropolis</City>
      <PostCode>9332</PostCode>
      <Country>New Zealand</Country>
    </Address>
  </Link>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/KeyContact" type="application/xml" title="KeyContact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/683/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/ChildOrganisations" type="application/xml" title="ChildOrganisations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/childorganisations/"/>
</Organisation>
Example 2

Update an existing organisation, and clear some existing values. Note the XML representation does not include an Email or WebsiteUrl value, or any Link entities for PostalAddress or KeyContact. Any existing values for these will be deleted as part of the operation.

PUT https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 936
<Organisation>
  <OrganisationID>823</OrganisationID>
  <Name>Acme Consultants</Name>
  <LegalName>Acme Consultants Limited</LegalName>
  <CodePrimary>ACMECONSUL04</CodePrimary>
  <CodeSecondary>74-582-821</CodeSecondary>
  <PhonePrimary>+64 4 211 2334</PhonePrimary>
  <PhoneSecondary>+64 4 211 2334 ext 231</PhoneSecondary>
  <Status>Active</Status>
  <CreatedDateTime>2009-11-23T02:49:59.493Z</CreatedDateTime>
  <LastModifiedDateTime>2009-11-25T02:11:32.174Z</LastModifiedDateTime>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/AccountManager" type="application/xml" title="AccountManager" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/32/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/ChildOrganisations" type="application/xml" title="ChildOrganisations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/childorganisations/"/>
</Organisation>

HTTP DELETE

Not supported.

HTTP PATCH

Performs a partial update of an Organisation by replacing parts of the representation with data from the request. Note that our PATCH implementation follows the draft RFC 5261 standard. Note that PATCH requests will be interpreted according to the RBAC permissions of the identity of the user on behalf of whom a request is being made.

The submitted Organisation representation can be/is often incomplete. Omitted properties will be ignored for the purposes of update.

Response

See HTTP response status codes for a general overview of all possible API status codes. Common response codes for PATCH operations are listed below.

Status Description
200 OK Resource was successfully updated.
400 Bad Request HTTP request body contains malformed or invalid parameters or is invalid according to our implementation of RFC 5261.
409 Conflict Resource could not be updated because it contains values that conflict with those on the server.
Example 1 - replacement

Simple update of the name of an existing organisation. Note the RFC style and nature of the XPath selector used in the sel attribute to target a specific part of the object graph for update.

PATCH https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/8123/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 101
<?xml version="1.0" encoding="UTF-8"?>
<diff>
  <replace sel="Organisation/Name/text()[1]">New company name</replace>
</diff>
Example 2 - remove and add

An alternative approach to changing the name of an organisation; remove it first, then add it.

PATCH https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/1423/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 187
<?xml version="1.0" encoding="UTF-8"?>
<diff>
  <remove sel="Organisation/Name"></remove>
  <add sel="Organisation/Name/text()[1]"><Name>New company name</Name></add>
</diff>
Example 3 - diff application ordering

In this valid diff document example, the final name of the organisation is being set to 'Clever People Limited', and not 'Cleverest of all'. This is because diff documents are processed 'in order'.

PATCH https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/1423/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 297
<?xml version="1.0" encoding="UTF-8"?>
<diff>
  <remove sel="Organisation/Name" />
  <add sel="Organisation"><Name>Cleverest of all</Name></add>
  <replace sel="Organisation/LegalName/text()[1]">Clever People Limited</replace>
  <replace sel="Organisation/Name/text()[1]">Clever People Limited</replace>
  <replace sel="Organisation/Email/text()[1]">info@cleverpeople.com</replace>
  <replace sel="Organisation/WebsiteUrl/text()[1]">www.cleverpeople.com</replace>
</diff>
Example 4 - bad request

Attempted update of the name of an existing organisation but with a malformed patch document.

PATCH https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/1510/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 89
<?xml version="1.0" encoding="UTF-8"?>
<diff>
  <remove sel="Organisation/Node"></remove>
</diff>

As the selector element refers to a non existent path, an error is returned along with an HTTP status of 400:

<?xml version="1.0" encoding="UTF-8"?>
<ApiException>
  <Code>BadRequest</Code>
  <Message>Path Organisation/Node did not match a node (line = 2, position = 3)</Message>
</ApiException>

Organisation collection resource

The Organisation collection resource represents the set of Organisation resources on the platform.

Resource URI

/api/2012-02-01/auth/resources/organisations/

HTTP GET

Returns a representation of the collection as a set of Link elements which can be followed to access individual Organisation resources, or link expansion can be used via the expand query parameter to inline the entities with the HTTP GET response. See querying collections for general information on handling resource collections.

Optional parameters
Parameter Description
expand Expression referencing Link elements to expand when generating the response. See link expansion.
filter A filter expression to apply to the collection. See collection filters. The following properties (and link titles) may be used in filter expressions:
  • OrganisationID
  • Name
  • LegalName
  • Email
  • CodePrimary
  • PhonePrimary
  • WebsiteUrl
  • Status
  • CreatedDateTime
  • LastModifiedDateTime
  • PostalAddress
  • PhysicalAddress
  • AccountManager
  • KeyContact
  • ParentOrganisation
orderby A sort expression to apply to the collection. See collection sorting. The following properties may be used in sort expressions:
  • OrganisationID
  • Name
  • LegalName
  • Email
  • CodePrimary
  • PhonePrimary
  • WebsiteUrl
  • CreatedDateTime
  • LastModifiedDateTime
skip Returns a subset of records from the collection, starting at index N+1 specified by this parameter. The skip and top parameters are generally used for collection paging.
top Returns a subset of records from the collection, starting at index 0 or index skip, and returns the first N records. The skip and top parameters are generally used for collection paging.
Example 1

Retrieve a collection of Organisation links with the default parameters, and no link expansion.

GET /api/2012-02-01/auth/resources/organisations/

<Organisations>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Organisation" type="application/xml" title="Organisation" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Organisation" type="application/xml" title="Organisation" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/824/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Organisation" type="application/xml" title="Organisation" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/825/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Organisation" type="application/xml" title="Organisation" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/826/"/>
  ...
  <Link rel="next" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/?skip=100"/>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/"/>
</Organisations>
Example 2

Retrieve a collection of Organisation links with the default parameters, with Organisation link expansion.

GET /api/2012-02-01/auth/resources/organisations/?expand=Organisation

<Organisations>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Organisation" type="application/xml" title="Organisation" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/">
    <Organisation>
      <OrganisationID>823</OrganisationID>
      <Name>Acme Consultants</Name>
      <LegalName>Acme Consultants Limited</LegalName>
      <Email>admin@acme.example.org</Email>
      <CodePrimary>ACMECONSUL04</CodePrimary>
      <CodeSecondary>74-582-821</CodeSecondary>
      <PhonePrimary>+64 4 211 2334</PhonePrimary>
      <PhoneSecondary>+64 4 211 2334 ext 231</PhoneSecondary>
      <WebsiteUrl>acme.example.org</WebsiteUrl>
      <Status>Active</Status>
      <CreatedDateTime>2009-11-23T02:49:59.493Z</CreatedDateTime>
      <LastModifiedDateTime>2009-11-25T02:11:32.174Z</LastModifiedDateTime>
      <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PostalAddress" type="application/xml" title="PostalAddress" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/postaladdress/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/AccountManager" type="application/xml" title="AccountManager" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/32/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/KeyContact" type="application/xml" title="KeyContact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/683/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/ChildOrganisations" type="application/xml" title="ChildOrganisations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/childorganisations/"/>
    </Organisation>
  </Link>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Organisation" type="application/xml" title="Organisation" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/824/">
    <Organisation>
      <OrganisationID>824</OrganisationID>
      <Name>Acme Engineering</Name>
      <LegalName>Acme Engineering Limited</LegalName>
      <Email>engineering@acme.example.org</Email>
      <CodePrimary>ACMEENGIN23</CodePrimary>
      <CodeSecondary>23-622-881</CodeSecondary>
      <PhonePrimary>+64 4 211 2314</PhonePrimary>
      <PhoneSecondary>+64 4 211 2314 ext 101</PhoneSecondary>
      <WebsiteUrl>acme.example.org</WebsiteUrl>
      <Status>Active</Status>
      <CreatedDateTime>2009-11-23T02:49:59.493Z</CreatedDateTime>
      <LastModifiedDateTime>2009-11-25T02:11:32.174Z</LastModifiedDateTime>
      <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/824/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PostalAddress" type="application/xml" title="PostalAddress" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/824/postaladdress/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/AccountManager" type="application/xml" title="AccountManager" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/32/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/KeyContact" type="application/xml" title="KeyContact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/683/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/ChildOrganisations" type="application/xml" title="ChildOrganisations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/824/childorganisations/"/>
    </Organisation>
  </Link>
  ...
  <Link rel="next" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/?expand=Organisation&skip=100"/>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/?expand=Organisation"/>
</Organisations>

HTTP POST

Creates a new Organisation in the collection.

The submitted Organisation representation must be complete with optional inline representations of PostalAddress and PhysicalAddress, but must not include system-managed properties:

  • OrganisationID
  • CreatedDateTime
  • LastModifiedDateTime
Response

See HTTP response status codes for a general overview of all possible API status codes. Common response codes for POST operations are listed below.

Status Description
201 Created Resource was successfully created. The body of the response will contain the new resource.
400 Bad Request HTTP request body contains malformed or invalid parameters.
409 Conflict Resource could not be created because it contains values that conflict with those on the server.
Example

Create a new organisation, including inline PostalAddress and KeyContact information for the new organisation.

The API response will include a representation of the organisation, including a newly-generated value for OrganisationID.

POST https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml
Content-Length: 1769
<Organisation>
  <Name>Acme Consultants</Name>
  <LegalName>Acme Consultants Limited</LegalName>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PostalAddress" type="application/xml" title="PostalAddress">
    <Address>
      <StreetLine1>98 Wallacetown Quay</StreetLine1>
      <StreetLine2>PO Box 98442</StreetLine2>
      <SuburbOrRegion>Northcote</SuburbOrRegion>
      <City>Metropolis</City>
      <PostCode>9332</PostCode>
      <Country>New Zealand</Country>
    </Address>
  </Link>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/KeyContact" type="application/xml" title="KeyContact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/683/"/>
</Organisation>
HTTP/1.1 201 Created
Content-Length: 2042
Content-Type: application/xml; charset=utf-8
<Organisation>
  <OrganisationID>823</OrganisationID>
  <Name>Acme Consultants</Name>
  <LegalName>Acme Consultants Limited</LegalName>
  <CreatedDateTime>2009-11-23T02:49:59.493Z</CreatedDateTime>
  <LastModifiedDateTime>2009-11-25T02:11:32.174Z</LastModifiedDateTime>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/PostalAddress" type="application/xml" title="PostalAddress" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/postaladdress/">
    <Address>
      <StreetLine1>98 Wallacetown Quay</StreetLine1>
      <StreetLine2>PO Box 98442</StreetLine2>
      <SuburbOrRegion>Northcote</SuburbOrRegion>
      <City>Metropolis</City>
      <PostCode>9332</PostCode>
      <Country>New Zealand</Country>
    </Address>
  </Link>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/KeyContact" type="application/xml" title="KeyContact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/683/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/ChildOrganisations" type="application/xml" title="ChildOrganisations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/childorganisations/"/>
</Organisation>

HTTP PUT

Not supported.

HTTP DELETE

Not supported.