Description

There are two main type of contacts in Winddle: Company and User. This service is dedicated to managing Company Contacts.

Company contacts can either be tied to a real Company or not - this is defined by their described_type / described_id field. When a contact is tied to a real company, the update options are very limited, only an admin of the Company being described by the contact can make any change.

Company contacts which aren’t tied directly to an actual Company are independent and can potentially be edited by anyone in the company, based on their position within the company.

This service only handles the contact’s basic fields and custom fields.

Params format (creation/update)

For this resource, all the params can be included in a key contact.

For instance, creating a company contact in XML (POST /api/v1/contacts/companies):

  <contact>
    <name>Chinese Factory</name>
    <role>factory</reference>
    <country>CHN</country>
  </contact>

In JSON, the root key is not necessary and the following body would be accepted:

  {
    "name": "Chinese Factory",
    "role": "factory",
    "country": "CHN"
  }

Contact base fields

Name	Type
id	Integer (unique)
name	String (2..100 chars)
source_id	String (max 255 chars)
city	String (max 255 chars)
country	String (enum value)
industry	String (enum value)
role	String (enum value)
website	String (max 255 chars)
employees	Integer
current_turnover	Float + currency field
previous_turnover	Float + currency field
year_founded	Integer
longitude	Float
latitude	Float
category_id	Integer
described_id	Integer
described_type	String (max 255 chars)
company_id	Integer
winddle_contact	Boolean
px75	String
px150	String
px500	String
created_at	Datetime
updated_at	Datetime

Associated resources

Sales and Operations contact

Sales and operations contact are the prefered way to declare direct contact (outside of Winddle) information.

They represent a relation to a User Contact (either a real Winddle account or an independent contact).

The association between a Contact User and a Contact Company can be made on create or on update, either by providing an ID to an existing Contact User (real or independent) or by providing the fields necessary to build and attach a new Contact User (necessarily independent).

To attach an existing contact:

  {
     "contact_sales_id": 1234,
     "contact_operations_id": 1234
  }

To remove an attached sales or operations contact, send the key with a null value:

  {
     "contact_sales_id": null,
     "contact_operations_id": null
  }

Finally, to create a new contact (here just for the contact sales, use contact_operations_attributes for the operations contact):

  {
     "contact_operations_attributes": {
        "first_name": "First Name",
        "last_name": "Last Name",
        "email": "user@email.com",
        "phone_number": "Phone Number",
        "skype": "Skype handle"
     }
  }

Described

The combination of the described_type and described_id contains the reference to the object this contact is ‘describing’ - in other words, a Winddle Company or Winddle User do not have any contact information, they need a contact to describe them and those 2 keys allow to find out which Winddle User/Company this contact is describing.

Alternatively, the winddle_contact boolean is set to true when the contact is tied to any real Winddle Company, false otherwise.

Those values are all read only, it’s not possible to manually describe an object with contact information, this is managed automatically by Winddle.

Contact company and dependent contacts

A contact company can be dependent on another contact company. The parent contact company will be in the key contact_company, with all of the contact’s base fields.

This is used to create relations between a supplier and a factory, or between a contact user and a contact company.

In general, if a user can access a contact company, then this user can also access all the directly dependent contacts.

Access

Access to contacts depends on complex rules, involving company partnerships, if the contact is dependent on another contact, if the contact has been created by the current user’s company or not, etc.

All those rules and details are computed by Winddle and the relevant summarized information is available in the access key.

access_companies contains an array of all the companies involved in the access to this contact. This is true both for indirect and direct access. For indirect access, this provides the necessary context to render the contact (including custom fields, categories, rating items…) and for direct access, this contains all the partner companies, as partner companies (for which the contact’s company is working) can provide additional custom fields to be filled.

Pending invitation

For contacts that haven’t yet been tied to any real Winddle User / Company, it’s possible to invite them on Winddle by providing an email - when the user has accepted the invitation and created the account, the contact’s ownership will be transfered to this new account and a partnership will be created to ensure continued access to the contact for the previous owner.

If there are currently any pending invitation, it’ll be in the pending_invitation key. There can only be one pending invitation at a time.

Attachments

The files attached to a contact are sent with the key attachments.

This key only include files directly attached to the contact (“Public documents”), not documents attached to workflow steps.

Customs

This array, sent in the key customs contains an entry for each Custom Fields created in any of the access companies (see Access section above) for this contact.

For each of those custom fields, the following keys are provided:

• id : id of the Custom Field
• name: name of the Custom FIeld
• value: value for this Contact, if any
• updated_at: Datetime of the update for the value, if any

Supported Formats

JSON XML