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
Documents for Activities Used to work with documents related to activities /activities/[activityld]/documents
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
Users Used to obtain users /users
Calendars Used to obtain calendars /calendars
Views Used for views filters /views
Sales order Used for sales order /salesorder
Sales order line Used for sales order line /salesorderline

 

In the seccions describing each entity, the following nomenclature will be used:

  • Mandatory: Y/N -> The field is not optional, must be informed when performing POST/PUT calls.
  • 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. 

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)   X  
name Name of the account X   X
vat_number Value Added Tax identification number of the account     X
ext_id External id of the account from third party system (ERP, CRM, Accounting System)     X
address_1 Address line 1     X
address_2 Address line 2      
postcode A Postcode     X
province_name Province name     X
city_name City name     X
country_id ID of the country for this account     X
phone Phone number      
phone_2 Other phone number      
mobile_phone Mobile phone number      
fax Fax number      
email Email address      
website Website URL      
comment Comments      
permission_level Permission level set from 1 to 5, 5 being the highest level of permission      
visible_to_all If yes, account is visible to everyone regardless of the level of permission      
geocode_latitude Geocode address for latitude coordinate      
geocode_longitude Geocode address for longitude coordinate      
geocoded If yes, account has geocode recorded (geocode_latitude, geocode_longitude). It’s calculated automatically by the system.   X  
geolocalisation_accuracy Accuracy radius based on information about cell towers and WiFi nodes that the mobile client can detect      
account_type_id ID of the type of account X    
account_status_id ID of the status of account      
branch_id ID of the branch this account is assigned to      
segment_id ID of the segment this account is assigned to      
sales_rep_id ID of the owner sales representative responsible for this account      
sales_rep_2_id ID of a sales representative responsible for this account      
sales_rep_3_id ID of a sales representative responsible for this account      
sales_rep_4_id ID of a sales representative responsible for this account      
sales_rep_5_id ID of a sales representative responsible for this account      
deleted_by ID of the user who deleted the account   X  
created_by ID of the user who created the account   X  
modified_by ID of the user who modified the account   X  
created_date Date of creation of the account   X  
modified_date Date of the last modification of the account or Creation date if the record has not been modified yet   X  
deleted_date Date of deletion of the account   X  
deleted If yes, the account has been deleted (archived)   X  
product_rate_id ID of the default product's rate for company      

 

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)   X  
gender Gender of the contact (Man, Woman) X    
first_name First Name of the contact X   X
last_name Last Name of the contact X   X
address Address line1 of the contact      
postcode Postcode of the contact     X
province_name Province name of the contact     X
city_name City name of the contact     X
country_id ID of the country this contact is assigned to      
mobile_phone Mobile phone of the contact      
landline_phone_number Landline phone number of the contact      
fax Fax number of the contact      
email Email address of the contact X   X
email_2 2nd Email address of the contact   X  
email_3 3rd Email address of the contact   X  
skype_id Skype id of the contact      
linkedin_web_address LinkedIn web address of the contact      
comment Comments for the contact      
permission_level Permission level set from 1 to 5, 5 being the highest level of permission   X  
sales_rep_id ID of the Sales Rep user this contact is assigned to      
account_id ID of the account this contact is assigned to X   X
contact_type_id ID of the contact type for the contact      
ext_id External id of the contact from third party system (ERP, CRM, Your System)     X
deleted_by ID of the user who deleted the contact   X  
created_by ID of the user who created the contact   X  
modified_by ID of the user who modified the contact   X  
created_date Date of creation of the contact   X  
modified_date Date of the last modification of the account   X  
deleted_date Date of deletion of the contact   X  
deleted If yes, the contact has been deleted (archived)   X  

 

 

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)   X  
comment Comments for the activity      
activity_date_time Date and time of the activity X    
is_checkin Yes if this is a check-in activity   X  
checkin_type Only relevant if is_checkin = True. Options are: Standard Checkin, Opportunity and FastCheckin      
checkout_date_time Check-out date and time of the activity, only used for check-out activity      
geocode_latitude Latitude of the activity only used for check-ins activity      
geocode_longitude Longitude of the activity only used for check-ins activity      
geocoded Yes if geocode exists for activity, only used for check-ins activity   X  
geocode_accuracy Geocode accuracy of the activity only used for check-ins activity      
permission_level Permission level set from 1 to 5, 5 being the highest level of permission      
sales_rep_id ID of the Sales Rep user this activity has been created for X   X
contact_id ID of the Contact this activity is assigned to     X
account_id ID of the account this activity is assigned to X   X
opportunity_id ID of the opportunity this activity is assigned to     X
activity_type_id ID of the activity type assigned to this activity. See [tblTiposGestion] for values X    
ext_id External id of the activity from third party system (ERP,CRM,Accouting System)     X
deleted_by ID of the user who deleted the activity   X  
created_by ID of the user who created the activity   X  
modified_by ID of the user who modified the activity   X  
created_date Date of creation of the contact   X  
modified_date Date of the last modification of the activity   X  
deleted_date Date of deletion of the activity   X  
deleted If yes, the activity has been deleted (archived)   X  

 

 

Documents for Activities

Supported methods: READ and DELETE.

The next table shows the documents for activities resource definition. As it’s only for read and delete, the mandatory, read-only and important properties are not required.

Field Description
Id Unique identifier for the document
name The name the document ( on the file system)
url The url to download the document

This object will return the url of the document, the idea is to perform a second GET request to this endpoint to download the file, it will have an expiration time larger than 4 hours. Sometimes documents are zippedfor efficiency reasons.

 

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)   X  
topic Topic of the opportunity X   X
comments Comments for the opportunity      
amount Amount of the opportunity      
probability Probability of the opportunity X    
won_date Date of which the opportunity has been won   X  
lost_date Date of which the opportunity has been lost   X  
closing_date_expected Date of which the opportunity is expected to be closed      
closed_date Date of which the opportunity has been closed      
geolocalisation_accuracy Accuracy radius based on information about cell towers and WiFi nodes that the mobile client can detect      
geocoded If yes, opportunity has geocode recorded (geocode_latitude, geocode_longitude)   X  
geocode_longitude Geocode address for latitude coordinate      
geocode_latitude Geocode address for longitude coordinate      
address Address line 1 of the opportunity      
address_2 Address line 2 of the opportunity      
postcode Postcode of the opportunity     X
province_name Province name of the opportunity     X
city_name City name of the opportunity     X
country_id ID of the country of the opportunity     X
permission_level Permission level set from 1 to 5, 5 being the highest level of permission      
status_id ID of the status of the opportunity X   X
sales_rep_id ID of the Sales Rep the opportunity is assigned to X    
account_id_1 ID of a related account of the opportunity - Specific for construction industry X   X
account_id_2 ID of a related account of the opportunity - Specific for construction industry      
account_id_3 ID of a related account of the opportunity - Specific for construction industry      
branch_id ID of the branch the opportunity is assigned to      
ext_id External id of the opportunity from third party system (ERP, CRM, Accounting System, etc…)     X
deleted_by ID of the user who deleted the opportunity   X  
created_by ID of the user who created the opportunity   X  
modified_by ID of the user who modified the opportunity   X  
created_date Date of creation of the opportunity   X  
modified_date Date of the last modification of the opportunity   X  
deleted_date Date of deletion of the opportunity   X  
deleted If yes, the opportunity has been deleted (archived)   X  
currency_id ID of the currency of the amount      

 

 

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)   X  
model Name of the product X   X
description A comment for the product     X
price Selling price for the product X    
category_id Id for the category of the product X   X
cost Manufacturing cost      
not_available If yes, the product is not available, otherwise it is accessible      
family_id Id for the family of the product     X
max_discount Maximum possible discount (%) over the product's price      
permission_level Permission level set from 1 to 5, 5 being the highest level of permission      
ext_id External id of the product from third party system (ERP, CRM, Accounting System)     X
read_only If yes, the product is read-only, otherwise it is not   X  
deleted If yes, the product has been deleted (archived)   X  
deleted_date Date of deletion of the product   X  
deleted_by ID of the user who deleted the product   X  
created_date Date of creation of the product   X  
created_by ID of the user who created the product   X  
modified_date Date of the last modification of the product   X  
modified_by ID of the user who modified the product   X  

 

 

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 regarding reading data for this resource, you could address the topic: Search List of Values.

For more information 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
type Which entity type should be used for searching, allowed values are:
• Company
• User
• Offer
• Product
• Contact
• Activity
• Schedule
Id The entity’s internal id

 

 

Users

Supported methods: READ.

The next table shows the user resource definition. As it’s only for read, the mandatory and read-only properties are not required.

Field Description Important
Id Unique identifier for the user  
branch_id ID of the branch the user is assigned to X
branch_name Name of the branch  
email Email of the user X
enabled The user is enabled: true/false  
first_name User’s first name X
last_name User’s last name X
last_geocode_accuracy_meters Last accuracy radius in meters based on information about cell towers an WiFi nodes that the mobile client can detect  
last_geocode_date The date when the last geocode address was saved  
last_geocode_latitude Last available geocode address for latitude coordinate  
last_geocode_longitude Last available geocode address for longitude coordinate  
mobile_phone The user’s cellphone number  
permission_level Permission level set from 1 to 5, 5 being the highest level of permission  
responsible_user_id The id of the user manager/responsible  
user_type_id The id for the user type X
user_type_description The user type description  
ext_id Externalid id of the user from third party system (ERP, CRM, Accounting System) X
deleted If yes, the user has been deleted (archived)  
deleted_date Date of deletion of the user  
deleted_by ID of the user who deleted the record  
created_date Date of creation of the user  
created_by ID of the user who created the user  
modified_date Date of the last modification of the user  
modified_by ID of the user who modified the user  

 

 

Calendars

Supported methods: CREATE, READ, UPDATE, and DELETE.

The nex table shows the calendar resource definition:

Field Description Mandatory Read-only Important
account_id Id for the account associated to this calendar     X
account_name Name of the account associated to this calendar   X  
activity_type_id Id of the activity type related to the calendar X   X
activity_type_name Description if activity type related to the calendar   X  
all_day The calendar is for the whole day: true/false   X  
branch_id Id of the branch the calendar is assigned to      
brach_name Name of the branch the calendar is linked to   X  
comments comments for the calendar   X  
completed the task was completed?:true/false      
contact_id The id of the contact associated to the calendar     X
contact_name The full name of the contact associated to the calendar   X  
created_by ID of the user who created the calendar   X  
created_date Date of creation of the calendar   X  
deleted If true the calendar has been deleted (archived)   X  
deleted_by Id of the user who deleted the record   X  
deleted_date Date of deletion of the calendar   X  
end_date Ending full date of the calendar X    
ext_id External id of the calendar from third party system ( ERP, CRM, Accounting System)     X
id Unique identifier for the calendar      
modified_by Id of the user who modified the calendar   X  
modified_date Date of the last modification of the calendar   X  
notification_minutes The minutes before start_date to raise an alert      
opportunity_id Id of the opportunity the calendars is linked to     X
opportunity_reference Reference of the opportunity the calendars is linked to   X  
owner_id Id of the owner for the calendar X   X
owner_name Full name of the owner for the calendar   X  
permission_level Permission level set from 1 to 5, 5 being the highest level of permission      
read_only If true, the calendar is read-only, otherwise it is not   X  
send_notification Send a notification: true/false      
stard_date Startinfg full date of the calendar X    
subject The subject of the calendar X   X
type The type of calendar: Task/event X   X

 

Views

Supported methods: CREATE, READ, UPDATE, and DELETE.

The table below shows the views resource definition:

Field Description Mandatory Read-only Important
id Unique identifier for the view (incremented on creation)   X  
name Name of the view  X     X 
entity Entity where the view filter was applied X   X
is_public The view is visible to all users      
is_active Activate or deactivate a view      
startdate Date the view filter was made visible      
enddate Date until when the view filter will be visible      
deleted If yes, the view has been deleted (archived)   X  
deleted_date View has been deleted (or archived)   X  
deleted_by ID of the user who deleted the view    X   
created_date Creation date of the view   X  
created_by ID of the user who created the view   X  
modified_date Date the view was last modified   X  
modified_by ID of the user who modified the view   X  
filter The filter for the view      
users List of users who can see this view filter if set as a non-public view      

 

Sales orders

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 sales order (incremented on creation)   X
topic Topic of the sales order  X   
comments Comments of the sales order     X
account_id Account identifier linked to the sales order     X
address Address line     X
contact_id Contact identifier linked to the sales order    
status_id Status identifier linked to the sales order     X
rate_id Rate identifier linked to the sales order    
discount_1 1st discount    
discount_2 2nd discount    
discount_3 3rd discount    
discount_4 4th discount    
deleted_by ID of the user who deleted the account    
created_by ID of the user who created the account    
modified_by ID of the user who modified the account    
created_date  Date of creation of the account    
modified_date Date of the last modification of the account or Creation date if the record has not been modified yet    
deleted_date Date of deletion of the account    
deleted If yes, the sales order has been deleted    
sales_rep_id Identifier of the REP sales    
closing_date_expected Expected closing date    
closed_date Closing date    
amount Amount    
archived If yes, the sales order has been archived    
year Current year of the sales order  
number Number   X
opportunity_id Opportunity identifier linked to the sales order    
currency_id Currency identifier linked to the sales order    
ext_id External identifier linked to the sales order    
branch_id Branch identifier linked to the sales order    

  

Sales orders lines

Supported methods: CREATE, READ, UPDATE, and DELETE.

The next table shows the company resource definition:

Field Description Mandatory Read-only Important
product_id  Identifier of the product linked to the sales order line    
salesorder_id  Identifier of the sales order linked to the sales order line  
quantity  Quantity of the sales order line     X
price  Price of the sales order line    
discount_1  1st discount     X
discount_2  2nd discount     X
discount_3  3rd discount     X
discount_4  4th discount     X
final_price  Final price of the sales order line     X

Esse artigo foi útil?
Registre-se para nos dar sua opinião sobre os nossos artigos.