Entity types
Introduction
In the FM RESTful API, the following entities are supported:
| Entity | Description | Base URL |
|---|---|---|
| Companies | Used to interact with companies | /companies |
| Contacts | Used to work with contacts | /contacts |
| Activities | Used for activities | /activities |
| Opportunities | Used for opportunities | /opportunities |
| Products | Used for products | /products |
| List of Values | Used to get list of values for entities | /values |
| Internal Ids | Used to get the FM id of an entity by your system id (external id) | /internalids |
In the sections describing each entity, the following nomenclature will be used:
- Mandatory: Y/N -> The field is not optional, must be informed.
- Read-only: Y/N -> The field is returned by the API, but if informed on a POST/PUT method the call is silently discarded.
- Important: Y/N ->The field is available on the Search by important fields. See section Search by important fields for more information.
Extra Fields
Every entity in the FM System can have extra fields, they are customer self-maintained fields included in the entity.
In the majority of cases, extra fields are treated as regular entity fields in text format. These types of fields can be recognized because they start with the prefix “z_” (without quotes).
For example: z_internal_currency, z_text_special, z_datetime are all valid extra fields.
The following json is an example of a Company with extra fields, you will notice a number of n extra fields at the end of the entity.
|
1
2
3
4
5
6
7
8
9
10
11
|
{
"id": "3400",
"name": "Test Company 2",
"address_1": "Company address 5",
"address_2": "Company address 6",
...
"z_extrafield_1": "Value extrafield 1",
"z_extrafield_2": "Value extrafield 2",
...
"z_extrafield_n": "Value extrafield n"
}
|
Extra fields can be operated as standard fields and always should be Strings (quotes).
Companies
Supported methods: CREATE, READ, UPDATE and DELETE.
The next table shows the company resource definition:
| Field | Description | Mandatory | Read-only | Important |
|---|---|---|---|---|
| id | Unique identifier for the account (incremented on creation) | N | Y | N |
| name | Name of the account | Y | N | Y |
| vat_number | Value Added Tax identification number of the account | N | N | Y |
| ext_id | External id of the account from third party system (ERP, CRM, Accounting System) | N | N | Y |
| address_1 | Address line 1 | N | N | Y |
| address_2 | Address line 2 | N | N | N |
| postcode | A Postcode | N | N | Y |
| province_name | Province name | N | N | Y |
| city_name | City name | N | N | Y |
| country_id | ID of the country for this account | N | N | Y |
| phone | Phone number | N | N | N |
| phone_2 | Other phone number | N | N | N |
| mobile_phone | Mobile phone number | N | N | N |
| fax | Fax number | N | N | N |
| Email address | N | N | N | |
| website | Website URL | N | N | N |
| comment | Comments | N | N | N |
| permission_level | Permission level set from 1 to 5, 5 being the highest level of permission | N | N | N |
| visible_to_all | If yes, account is visible to everyone regardless of the level of permission | N | N | N |
| geocode_latitude | Geocode address for latitude coordinate | N | N | N |
| geocode_longitude | Geocode address for longitude coordinate | N | N | N |
| geocoded | If yes, account has geocode recorded (geocode_latitude, geocode_longitude). It’s calculated automatically by the system. | N | Y | N |
| geolocalisation_accuracy | Accuracy radius based on information about cell towers and WiFi nodes that the mobile client can detect | N | N | N |
| account_type_id | ID of the type of account | Y | N | N |
| branch_id | ID of the branch this account is assigned to | N | N | N |
| segment_id | ID of the segment this account is assigned to | N | N | N |
| sales_rep_id | ID of the owner sales representative responsible for this account | N | N | N |
| sales_rep_2_id | ID of a sales representative responsible for this account | N | N | N |
| sales_rep_3_id | ID of a sales representative responsible for this account | N | N | N |
| sales_rep_4_id | ID of a sales representative responsible for this account | N | N | N |
| sales_rep_5_id | ID of a sales representative responsible for this account | N | N | N |
| deleted_by | ID of the user who deleted the account | N | Y | N |
| created_by | ID of the user who created the account | N | Y | N |
| modified_by | ID of the user who modified the account | N | Y | N |
| created_date | Date of creation of the account | N | Y | N |
| modified_date | Date of the last modification of the account or Creation date if the record has not been modified yet | N | Y | N |
| deleted_date | Date of deletion of the account | N | Y | N |
| deleted | If yes, the account has been deleted (archived) | N | Y | N |
| product_rate_id | ID of the default product's rate for company | N | N | N |
Contacts
Supported methods: CREATE, READ, UPDATE and DELETE.
The next table shows the contact resource definition:
| Field | Description | Mandatory | Read-only | Important |
|---|---|---|---|---|
| id | Unique identifier for the contact (incremented on creation) | N | Y | N |
| gender | Gender of the contact (Man, Woman) | Y | N | N |
| first_name | First Name of the contact | Y | N | Y |
| last_name | Last Name of the contact | Y | N | Y |
| address | Address line1 of the contact | N | N | N |
| postcode | Postcode of the contact | N | N | Y |
| province_name | Province name of the contact | N | N | Y |
| city_name | City name of the contact | N | N | Y |
| country_id | ID of the country this contact is assigned to | N | N | N |
| mobile_phone | Mobile phone of the contact | N | N | N |
| landline_phone_number | Landline phone number of the contact | N | N | N |
| fax | Fax number of the contact | N | N | N |
| Email address of the contact | Y | N | Y | |
| email_2 | 2nd Email address of the contact | N | Y | N |
| email_3 | 3rd Email address of the contact | N | Y | N |
| skype_id | Skype id of the contact | N | N | N |
| linkedin_web_address | LinkedIn web address of the contact | N | N | N |
| comments | Comments for the contact | N | N | N |
| permission_level | Permission level set from 1 to 5, 5 being the highest level of permission | N | Y | N |
| sales_rep_id | ID of the Sales Rep user this contact is assigned to | N | N | N |
| account_id | ID of the account this contact is assigned to | Y | N | Y |
| contact_type_id | ID of the contact type for the contact | N | N | N |
| ext_id | External id of the contact from third party system (ERP, CRM, Your System) | N | N | Y |
| deleted_by | ID of the user who deleted the contact | N | Y | N |
| created_by | ID of the user who created the contact | N | Y | N |
| modified_by | ID of the user who modified the contact | N | Y | N |
| created_date | Date of creation of the contact | N | Y | N |
| modified_date | Date of the last modification of the account | N | Y | N |
| deleted_date | Date of deletion of the contact | N | Y | N |
| deleted | If yes, the contact has been deleted (archived) | N | Y | N |
Activities
Supported methods: CREATE, READ, UPDATE and DELETE..
The next table shows the activity resource definition:
| Field | Description | Mandatory | Read-only | Important |
|---|---|---|---|---|
| id | Unique identifier for the contact (incremented on creation) | N | Y | N |
| comment | Comments for the activity | N | N | N |
| activity_date_time | Date and time of the activity | Y | N | N |
| is_checkin | Yes if this is a check-in activity | N | Y | N |
| checkin_type | Only relevant if is_checkin = True. Options are: Standard Checkin, Opportunity and FastCheckin | N | N | N |
| checkout_date_time | Check-out date and time of the activity, only used for check-out activity | N | N | N |
| geocode_latitude | Latitude of the activity only used for check-ins activity | N | N | N |
| geocode_longitude | Longitude of the activity only used for check-ins activity | N | N | N |
| geocoded | Yes if geocode exists for activity, only used for check-ins activity | N | Y | N |
| geocode_accuracy | Geocode accuracy of the activity only used for check-ins activity | N | N | N |
| permission_level | Permission level set from 1 to 5, 5 being the highest level of permission | N | N | N |
| sales_rep_id | ID of the Sales Rep user this activity has been created for | Y | N | Y |
| contact_id | ID of the Contact this activity is assigned to | N | N | Y |
| account_id | ID of the account this activity is assigned to | Y | N | Y |
| opportunity_id | ID of the opportunity this activity is assigned to | N | N | Y |
| activity_type_id | ID of the activity type assigned to this activity. See [tblTiposGestion] for values | Y | N | N |
| ext_id | External id of the activity from third party system (ERP,CRM,Accouting System) | N | N | Y |
| deleted_by | ID of the user who deleted the activity | N | Y | N |
| created_by | ID of the user who created the activity | N | Y | N |
| modified_by | ID of the user who modified the activity | N | Y | N |
| created_date | Date of creation of the contact | N | Y | N |
| modified_date | Date of the last modification of the activity | N | Y | N |
| deleted_date | Date of deletion of the activity | N | Y | N |
| deleted | If yes, the activity has been deleted (archived) | N | Y | N |
Opportunities
Supported methods: CREATE, READ, UPDATE and DELETE.
The next table shows the opportunity resource definition:
| Field | Description | Mandatory | Read-only | Important |
|---|---|---|---|---|
| id | Unique identifier for the opportunity (incremented on creation) | N | Y | N |
| topic | Topic of the opportunity | Y | N | Y |
| comments | Comments for the opportunity | N | N | N |
| amount | Amount of the opportunity | N | N | N |
| probability | Probability of the opportunity | Y | N | N |
| won_date | Date of which the opportunity has been won | N | Y | N |
| lost_date | Date of which the opportunity has been lost | N | Y | N |
| closing_date_expected | Date of which the opportunity is expected to be closed | N | N | N |
| closed_date | Date of which the opportunity has been closed | N | N | N |
| geolocalisation_accuracy | Accuracy radius based on information about cell towers and WiFi nodes that the mobile client can detect | N | N | N |
| geocoded | If yes, opportunity has geocode recorded (geocode_latitude, geocode_longitude) | N | Y | N |
| geocode_longitude | Geocode address for latitude coordinate | N | N | N |
| geocode_latitude | Geocode address for longitude coordinate | N | N | N |
| address | Address line 1 of the opportunity | N | N | N |
| address_2 | Address line 2 of the opportunity | N | N | N |
| postcode | Postcode of the opportunity | N | N | Y |
| province_name | Province name of the opportunity | N | N | Y |
| city_name | City name of the opportunity | N | N | Y |
| country_id | ID of the country of the opportunity | N | N | Y |
| permission_level | Permission level set from 1 to 5, 5 being the highest level of permission | N | N | N |
| status_id | ID of the status of the opportunity | Y | N | Y |
| sales_rep_id | ID of the Sales Rep the opportunity is assigned to | Y | N | N |
| account_id_1 | ID of a related account of the opportunity - Specific for construction industry | Y | N | Y |
| account_id_2 | ID of a related account of the opportunity - Specific for construction industry | N | N | N |
| account_id_3 | ID of a related account of the opportunity - Specific for construction industry | N | N | N |
| branch_id | ID of the branch the opportunity is assigned to | N | N | N |
| ext_id | External id of the opportunity from third party system (ERP, CRM, Accounting System, etc…) | N | N | Y |
| deleted_by | ID of the user who deleted the opportunity | N | Y | N |
| created_by | ID of the user who created the opportunity | N | Y | N |
| modified_by | ID of the user who modified the opportunity | N | Y | N |
| created_date | Date of creation of the opportunity | N | Y | N |
| modified_date | Date of the last modification of the opportunity | N | Y | N |
| deleted_date | Date of deletion of the opportunity | N | Y | N |
| deleted | If yes, the opportunity has been deleted (archived) | N | Y | N |
Products
Supported methods: CREATE, READ, UPDATE and DELETE.
The next table shows the product resource definition:
| Field | Description | Mandatory | Read-only | Important |
|---|---|---|---|---|
| id | Unique identifier for the product ( incremented on creation) | N | Y | N |
| model | Name of the product | Y | N | Y |
| description | A comment for the product | N | N | Y |
| price | Selling price for the product | Y | N | N |
| category_id | ID for the category of the product | Y | N | Y |
| cost | Manufacturing cost | N | N | N |
| not available | If yes, the product is not available, otherwise it is accessible | N | N | N |
| family_id | ID for the family of the product | N | N | Y |
| max_discount | Maximum possible discount (%) over the product's price | N | N | N |
| permission_level | permission level set from 1 to 5, 5 being the highest level of permission | N | N | N |
| ext_id | External id of the product from third party system (ERP, CRM, Accounting System) | N | N | Y |
| read_only | If yes, the product is read-only, otherwise it is not | N | Y | N |
| deleted | If yes, the product has been deleted ( archived) | N | Y | N |
| deleted_date | Date of deletion of the product | N | Y | N |
| deleted_by | ID of the user who deleted the product | N | Y | N |
| created_date | Date of creation of the product | N | Y | N |
| created_by | ID of the user who creatd the product | N | Y | N |
| modified_date | Date of the last modification of the product | N | Y | N |
| modified_by | ID of the user who modified the product | N | Y | N |
List of Values
Supported methods: CREATE, READ, UPDATE, and DELETE..
List of values are dynamic, which means they don’t have a standard definition format as others do. Depending on specific parameters informed on the calls, results would vary on each one, and therefore cannot be summarized.
For more information for regarding data for this resource, you could address the topic: Search List of Values.
For more information for regarding/inserting/updating/deleting data for this resource, you could address the topic: Performing operations on Lists of Values
Internal Ids
Supported methods: READ
The next table shows the internal ids resource definition. As it’s only for read, the mandatory, read-only and important properties are not required:
| Field | Description |
|---|---|
| Company User Offer Product Contact Activity Schedule |
|
| Id | Id The entity’s internal id |