Contacts::companies

Manage company contacts (own profile, owned contacts, ...)

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

NameType
idInteger (unique)
nameString (2..100 chars)
source_idString (max 255 chars)
cityString (max 255 chars)
countryString (enum value)
industryString (enum value)
roleString (enum value)
websiteString (max 255 chars)
employeesInteger
current_turnoverFloat + currency field
previous_turnoverFloat + currency field
year_foundedInteger
longitudeFloat
latitudeFloat
category_idInteger
described_idInteger
described_typeString (max 255 chars)
company_idInteger
winddle_contactBoolean
px75String
px150String
px500String
created_atDatetime
updated_atDatetime

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

GET /api/v1/contacts/companies/:id

Retrieve everything about the contact

Params

Param name Description
id
required

Contact id, name, source_name or source_id

Must be a String or an Integer

POST /api/v1/contacts/companies

Create a company contact

Params

Param name Description
source_id
optional

ID in Customer’s source system (optional, max 255 char.)

Must be a String
source_name
optional

Name in Customer’s source system (optional, max 255 char.)

Must be a String
website
optional

Website URL

Must be a String
description
optional

Note/description (text)

Must be a String
country
optional

Main country (may be overwritten by address)

Must be one of: FRA, CHN, ABW, AFG, AGO, AIA, ALA, ALB, AND, ARE, ARG, ARM, ASM, ATA, ATF, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BES, BFA, BGD, BGR, BHR, BHS, BIH, BLM, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BVT, BWA, CAF, CAN, CCK, CHE, CHL, CIV, CMR, COD, COG, COK, COL, COM, CPV, CRI, CUB, CUW, CXR, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESH, ESP, EST, ETH, FIN, FJI, FLK, FRO, FSM, GAB, GBR, GEO, GGY, GHA, GIB, GIN, GLP, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUF, GUM, GUY, HKG, HMD, HND, HRV, HTI, HUN, IDN, IMN, IND, IOT, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JEY, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MSR, MTQ, MUS, MWI, MYS, MYT, NAM, NCL, NER, NFK, NGA, NIC, NIU, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PCN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, REU, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SGS, SHN, SJM, SLB, SLE, SLV, SMR, SOM, SPM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKL, TKM, TLS, TON, TTO, TUN, TUR, TUV, TWN, TZA, UGA, UKR, UMI, URY, USA, UZB, VAT, VCT, VEN, VGB, VIR, VNM, VUT, WLF, WSM, YEM, ZAF, ZMB, ZWE.
city
optional

Main city (may be overwritten by address)

Must be a String
industry
optional

Industry

Must be one of: professional_services, transportation, household_durables, leisure_products, textiles, apparel_accessories, retailing, household_personal, other_industry.
role
optional

Role

Must be one of: buyer, supplier, factory, agent, logistics, quality, service, customer, other.
years_founded
optional

Number of employees

Must be a Integer
employees
optional

Year founded

Must be a Integer
current_turnover
optional

Turnover (current year)

Must be a Float
previous_turnover
optional

Turnover (previous year)

Must be a Float
current_turnover_currency
optional
Must be one of: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, USD, ZBW.
previous_turnover_currency
optional
Must be one of: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, USD, ZBW.
image
optional

Avatar for the company

Multipart encoded file
remove_image
optional

Set to true to remove the current avatar, reset to default

Boolean (true/false)
markets
optional

Array of strings, contact’s main markets

Must be an array of any type
customers
optional

Array of strings, contact’s main customers

Must be an array of any type
customs
optional

Custom values for the Contact

An array of Custom Values for the Product.

Each element of this array should have the following format:

{
 field: The Winddle ID or the Name of the Custom Field
 value: The value for this field
}

Not providing a value for a Field will leave it as blank or keep its current value if any has been set.

main_address
optional

Main address for the contact (address_1, address_2, city, zipcode, state, zipcode)

Must be a Hash
billing_address
optional

Billing address for the contact (address_1, address_2, city, zipcode, state, zipcode)

Must be a Hash
clear_billing_address
optional

Set to true to reset the billing address

Boolean (true/false)
clear_main_address
optional

Set to true to reset the main address, city and country

Boolean (true/false)
name
required

Name, maximum 100 chars

Must be a String

PUT /api/v1/contacts/companies/:id

Update a company contact

Params

Param name Description
source_id
optional

ID in Customer’s source system (optional, max 255 char.)

Must be a String
source_name
optional

Name in Customer’s source system (optional, max 255 char.)

Must be a String
website
optional

Website URL

Must be a String
description
optional

Note/description (text)

Must be a String
country
optional

Main country (may be overwritten by address)

Must be one of: FRA, CHN, ABW, AFG, AGO, AIA, ALA, ALB, AND, ARE, ARG, ARM, ASM, ATA, ATF, ATG, AUS, AUT, AZE, BDI, BEL, BEN, BES, BFA, BGD, BGR, BHR, BHS, BIH, BLM, BLR, BLZ, BMU, BOL, BRA, BRB, BRN, BTN, BVT, BWA, CAF, CAN, CCK, CHE, CHL, CIV, CMR, COD, COG, COK, COL, COM, CPV, CRI, CUB, CUW, CXR, CYM, CYP, CZE, DEU, DJI, DMA, DNK, DOM, DZA, ECU, EGY, ERI, ESH, ESP, EST, ETH, FIN, FJI, FLK, FRO, FSM, GAB, GBR, GEO, GGY, GHA, GIB, GIN, GLP, GMB, GNB, GNQ, GRC, GRD, GRL, GTM, GUF, GUM, GUY, HKG, HMD, HND, HRV, HTI, HUN, IDN, IMN, IND, IOT, IRL, IRN, IRQ, ISL, ISR, ITA, JAM, JEY, JOR, JPN, KAZ, KEN, KGZ, KHM, KIR, KNA, KOR, KWT, LAO, LBN, LBR, LBY, LCA, LIE, LKA, LSO, LTU, LUX, LVA, MAC, MAF, MAR, MCO, MDA, MDG, MDV, MEX, MHL, MKD, MLI, MLT, MMR, MNE, MNG, MNP, MOZ, MRT, MSR, MTQ, MUS, MWI, MYS, MYT, NAM, NCL, NER, NFK, NGA, NIC, NIU, NLD, NOR, NPL, NRU, NZL, OMN, PAK, PAN, PCN, PER, PHL, PLW, PNG, POL, PRI, PRK, PRT, PRY, PSE, PYF, QAT, REU, ROU, RUS, RWA, SAU, SDN, SEN, SGP, SGS, SHN, SJM, SLB, SLE, SLV, SMR, SOM, SPM, SRB, SSD, STP, SUR, SVK, SVN, SWE, SWZ, SXM, SYC, SYR, TCA, TCD, TGO, THA, TJK, TKL, TKM, TLS, TON, TTO, TUN, TUR, TUV, TWN, TZA, UGA, UKR, UMI, URY, USA, UZB, VAT, VCT, VEN, VGB, VIR, VNM, VUT, WLF, WSM, YEM, ZAF, ZMB, ZWE.
city
optional

Main city (may be overwritten by address)

Must be a String
industry
optional

Industry

Must be one of: professional_services, transportation, household_durables, leisure_products, textiles, apparel_accessories, retailing, household_personal, other_industry.
role
optional

Role

Must be one of: buyer, supplier, factory, agent, logistics, quality, service, customer, other.
years_founded
optional

Number of employees

Must be a Integer
employees
optional

Year founded

Must be a Integer
current_turnover
optional

Turnover (current year)

Must be a Float
previous_turnover
optional

Turnover (previous year)

Must be a Float
current_turnover_currency
optional
Must be one of: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, USD, ZBW.
previous_turnover_currency
optional
Must be one of: AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTC, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLF, CLP, CNY, COP, CRC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EEK, EGP, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, USD, ZBW.
image
optional

Avatar for the company

Multipart encoded file
remove_image
optional

Set to true to remove the current avatar, reset to default

Boolean (true/false)
markets
optional

Array of strings, contact’s main markets

Must be an array of any type
customers
optional

Array of strings, contact’s main customers

Must be an array of any type
customs
optional

Custom values for the Contact

An array of Custom Values for the Product.

Each element of this array should have the following format:

{
 field: The Winddle ID or the Name of the Custom Field
 value: The value for this field
}

Not providing a value for a Field will leave it as blank or keep its current value if any has been set.

main_address
optional

Main address for the contact (address_1, address_2, city, zipcode, state, zipcode)

Must be a Hash
billing_address
optional

Billing address for the contact (address_1, address_2, city, zipcode, state, zipcode)

Must be a Hash
clear_billing_address
optional

Set to true to reset the billing address

Boolean (true/false)
clear_main_address
optional

Set to true to reset the main address, city and country

Boolean (true/false)
name
optional

Name, maximum 100 chars

Must be a String

PATCH /api/v1/contacts/companies/:id/invite

Invite someone on Winddle to take ownership of the contact

Params

Param name Description
email
optional

Email of the owner to invite

Must be a String
introduction
optional

Introduction text for the invitation email

Must be a String
position
optional
A Winddle Position. Can be either a position ID (unique integer) or a position Name (which must be unique within the company).

PATCH /api/v1/contacts/companies/:id/cancel_invitation

Cancel any pending invitation on this contact

DELETE /api/v1/contacts/companies/:id

Destroy the contact and all associated ressources

This operation isn’t possible if the contact has any dependent contacts. Those must be removed manually beforehand.