Arlo

REST Auth API: Organisation KeyContacts

Key contacts are a subresource of an Organisation resource representing a collection of Contact references of individuals responsible for managing the account relationship.

The collection is priority-sensitive. The first of the contacts is considered the KeyContact (or primary contact) for the organisation.

This resource supports retrieval of the collection of contacts for a given organisation, updating the collection with new references, and deleting individual references.

KeyContact collection resource

The KeyContact collection resource represents the set of KeyContact resources on the platform for the specified organisation.

Supports retrieval of the list of contacts via HTTP GET, and the replacing/updating the list via HTTP PUT.

Resource URI

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

HTTP GET

Returns a representation of the collection as a set of Link elements which can be followed to access individual Contact 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 Not supported.
orderby Not supported.
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 KeyContact links with the default parameters, and no link expansion.

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

<Contacts>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/35/"/>
  ...
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/keycontacts/"/>
</Contacts>
Example 2

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

GET /api/2012-02-01/auth/resources/organisations/823/keycontacts/?expand=Contact

<Contacts>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/">
    <Contact>
      <ContactID>12</ContactID>
      <UniqueIdentifier>6f20b4b1-20e9-496c-979a-81e98c0631d5</UniqueIdentifier>
      <FirstName>John</FirstName>
      <LastName>Doe</LastName>
      <Email>john.doe@demo.arlo.co</Email>
      <CodePrimary>JD_1</CodePrimary>
      <PhoneWork>+64 4 123 4567</PhoneWork>
      <PhoneMobile>+64 27 123 4567</PhoneMobile>
      <Status>Active</Status>
      <CreatedDateTime>2016-03-03T12:08:20.583Z</CreateDateTime>
      <LastModifiedDateTime>2020-05-14T02:51:23.865Z</LastModifiedDateTime>
      <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/"/>
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/CustomFields" type="application/xml" title="CustomFields" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/customfields/">
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/PostalAddress" type="application/xml" title="PostalAddress" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/postaladdress/">
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/Employment" type="application/xml" title="Employment" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/employment/">
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/Tags" type="application/xml" title="Tags" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/tags/">
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/TimeZone" type="application/xml" title="TimeZone" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/timezones/">
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/Regions" type="application/xml" title="Regions" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/regions
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/IntegrationData" type="application/xml" title="IntegrationData" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/integrationdata/">/">
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/Registrations" type="application/xml" title="Registrations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/registrations/">
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/Marketing" type="application/xml" title="Marketing" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/marketing/">
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/PresenterIdentity" type="application/xml" title="PresenterIdentity" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/presenteridentity/">
      <Link rel="http://schemas.arlo.co/api/2012/02/auth/Security" type="application/xml" title="Security" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/security/">
    </Contact>
  </Link>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/">
  <Contact>
    <ContactID>23</ContactID>
    <UniqueIdentifier>33ceb988-fd00-4286-9df3-49d4c7fccd8c</UniqueIdentifier>
    <FirstName>Jane</FirstName>
    <LastName>Doe</LastName>
    <Email>jane.doe@demo.arlo.co</Email>
    <CodePrimary>JD_1</CodePrimary>
    <PhoneWork>+64 4 123 4567</PhoneWork>
    <PhoneMobile>+64 27 123 4567</PhoneMobile>
    <Status>Active</Status>
    <CreatedDateTime>2016-03-03T12:08:20.583Z</CreateDateTime>
    <LastModifiedDateTime>2020-05-14T02:51:23.865Z</LastModifiedDateTime>
    <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/"/>
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/CustomFields" type="application/xml" title="CustomFields" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/customfields/">
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/PostalAddress" type="application/xml" title="PostalAddress" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/postaladdress/">
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/Employment" type="application/xml" title="Employment" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/employment/">
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/Tags" type="application/xml" title="Tags" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/tags/">
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/TimeZone" type="application/xml" title="TimeZone" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/timezones/">
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/Regions" type="application/xml" title="Regions" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/regions
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/IntegrationData" type="application/xml" title="IntegrationData" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/integrationdata/">/">
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/Registrations" type="application/xml" title="Registrations" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/registrations/">
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/Marketing" type="application/xml" title="Marketing" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/marketing/">
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/PresenterIdentity" type="application/xml" title="PresenterIdentity" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/presenteridentity/">
    <Link rel="http://schemas.arlo.co/api/2012/02/auth/Security" type="application/xml" title="Security" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/security/">
  </Contact>
</Link>
  ...
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/keycontacts/?expand=Contact"/>
</Contacts>

HTTP POST

Not supported.

To add a new key contact, use HTTP PUT to replace the collection with a copy that includes an additional contact reference.

HTTP PUT

Replaces the collection of key contacts for the organisation with a new copy.

The request body must be a <Contacts> collection element containing <Link> elements referencing existing Contact resources. All referenced contacts must already exist on the platform.

The replacement collection must be a complete representation and represents your desired state for the list. Any contacts not referenced that were previously key contacts will be removed from the key contacts list.

Inline content within <Link> elements is not supported and will result in a 400 Bad Request. New contacts cannot be created through this endpoint.

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
200 OK The collection of key contacts for the organisation was replaced with a new copy. The response body will contain the new collection of key contacts.
400 Bad Request HTTP request body contains malformed or invalid parameters, or includes inline elements within Link entries.
Example 1

Set the key contacts for organisation 823 to contacts 12 and 23. Any existing key contacts for the organisation will be replaced with these two references. The KeyContact for the organisation will also be updated to be contact with ID 12 (the first contact in the list).

PUT https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/keycontacts/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml

<Contacts>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/related/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/"/>
</Contacts>
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Length: 217

<Contacts>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/12/"/>
  <Link rel="http://schemas.arlo.co/api/2012/02/auth/Contact" type="application/xml" title="Contact" href="https://demo.arlo.co/api/2012-02-01/auth/resources/contacts/23/"/>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/keycontacts/"/>
</Contacts>
Example 2

Clear the key contacts for organisation 823 by replacing it with an empty list. The KeyContact for the organisation will also be cleared.

PUT https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/keycontacts/ HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
Content-Type: application/xml

<Contacts />
        
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Length: 64

<Contacts>
  <Link rel="self" type="application/xml" href="https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/keycontacts/"/>
</Contacts>

HTTP DELETE

Not supported.

To clear the list of key contacts, use collection HTTP PUT with an empty collection. To remove an individual contact from the key contacts, use instance HTTP DELETE.

KeyContact instance resource

The KeyContact instance resource represents a single key contact association for the specified organisation.

Resource URI

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

HTTP GET

Not supported.

HTTP POST

Not supported.

HTTP PUT

Not supported.

HTTP DELETE

Removes the specified contact from the organisation's key contacts. This does not delete the underlying Contact resource; it only removes the key contact association.

To delete multiple contacts (or clear all key contacts) from the organisation, use the collection HTTP PUT.

Response

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

Status Description
204 No Content Key contact association was successfully removed. No response body is returned.
404 Not Found The specified organisation does not exist, or the key contact association does not exist.
Example

Remove contact 12 as a key contact from organisation 823.

DELETE https://demo.arlo.co/api/2012-02-01/auth/resources/organisations/823/keycontacts/12 HTTP/1.1
Accept: application/xml
Accept-Encoding: gzip, deflate
        
HTTP/1.1 204 No Content