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
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 Fieldname
: name of the Custom FIeldvalue
: value for this Contact, if anyupdated_at
: Datetime of the update for the value, if any
Supported Formats
JSON XMLGET /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 , forwarder , quality , service , customer , carrier , 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:
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 , forwarder , quality , service , customer , carrier , 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:
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
PATCH /api/v1/contacts/companies/merge
Merge one or more contacts into another one. Merged contacts
Params
Param name | Description |
---|---|
merge required |
Array of winddle ID of the contacts to merge into |
into required |
Merge the contacts into this contact Must be a String or an Integer |
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.