Prophet CRM API Guide - Avidian

Avid CRM API Guide

Schedule a Demo

Avid CRM API

The Avid CRM API is a RESTful Api.

Helpful Resources

We recommend the thorough documentation of ODATA2 API conventions here: ODATA V2 Documentation

Additionally, we recommend Postman when interacting with the API.

Authentication

Auth: Basic (Login via auth headers)

In Postman, put the Avid user credential in Authorization tab:

For programing language, use based64 to encode username:password, so you get a the encoded value, i.e. dXNlcm5hbWU6cGFzc3dvcmQ=

Append Basic to the front of the Based64 Encoded username:password so you have something like “Basic dXNlcm5hbWU6cGFzc3dvcmQ=” as your authorization header value, and then set the Authorization header of the request to that authorization header value.

Example in JavaScript:

let auth = 'Basic ' + Buffer.from(username + ':' + password).toString('base64');
request.headers.authorization = 'Authorization: ' + auth;

HTTP Request Body

JSON, occasionally XML for linking entities.

Tenant

US Production https://prophetOnDemand.com/prophet/prophetwebservices/AvtProphetApi/odata/

Limitations

Read Only Tables:

Read Only tables have 'Views' denoted in the table name.

/ContactViews
/CompanyViews
/OpportunityViews

Currently queries to /CustomFieldValueTextNumerics and /CustomFieldValueTextMemos are now supported.

Supported HTTP Calls

Get
Patch
Post
Delete

Example of a GET call returning a specific Contact by their Id.

API Entities

Contacts

/Contacts
/ContactViews
/ContactNoteTrackings

Companies

/Companies
/CompanyViews

Opportunities

/Opportunities
/OpportunityViews
/OpportunityStageChangeHistory
/OpportunityProducts

Users

/Users
/'entity' $expand AssignedUsers

Templates

/Templates

Templates are customized by system administrators. Fields are located on templates.

Companies and Contacts utilize a global template while Opportunities utilize the template for the designated department.

Departments

/Departments

Users and Opportunities are associated with a specific department. Each department has an assigned Opportunity Template.

Custom Fields

/CustomFieldDefinitions
/CustomFieldDefinitionDropdownValues
/CustomFieldValueTexts
/CustomFieldValueDates
/CustomFieldValueDropdowns
/CustomFieldValueTextMemos
/CustomFieldValueTextNumerics

/CustomFieldDefinitions

Defines the field name and location within Avid.

{ 
    "Name": "complabel43", 
    "DisplayName": "complabel43", 
    "EntityType": "Company", 
    "FieldType": "Text", 
    "TemplateId": "bd1528ea-4b69-423e-bd10-70d6783f5e6d", 
    "Visible": false, 
    "VisibleMobile": false, 
    "VisibilityOrder": 0, 
    "FieldGroupId": null, 
    "Id": "651d64b4-2b44-401e-8b41-00a6220c7f55" 
}

/CustomFieldDefinitionDropdownValues

Represents a system dropdown value, the template it is associated with, and the field location.

{
    "CustomFieldDefinitionId": "3ec3cb11-db4d-42be-b5c9-fb9d42ed4e1e", 
    "Value": "Left Voicemail", 
    "TemplateId": "102d0325-ad0e-40dc-be49-032a6d529813", 
    "Id": "0c21c921-25b6-4fd5-b3e7-008164b3fe34"
}

/CustomFieldValueDropdowns

Represents a dropdown value entered by a user on an entity. Includes the entity, the DropDownValueId, and the field location.

{
    "CustomFieldDefinitionId": "b26e1d31-2595-4782-b430-73744d0d184b",
    "EntityId": "66e8ed08-335b-4729-bcfa-20f16ba5bb93",
    "Id": "b370c7f1-7c0c-4f50-90eb-00912202ded5",
    "DropDownValueId": "c330834e-4c9e-4414-84ec-4ba48ddd25fa"
}

/CustomFieldValueTexts

Represents a text value entered by a user, the entity it is associated with, and the location of the field where the text is entered.

{ 
    "CustomFieldDefinitionId": "e4e9fe54-ca00-43d5-9d4a-cd559f808050", 
    "EntityId": "29f871f8-355d-4e29-bcad-b854b78769d1", 
    "Id": "998399c8-f1c8-4328-82ad-0133742c4f25", 
    "Text": "Snacks" 
}

/CustomFieldValueDates

Represents a date value entered by a user, the entity it is associated with, and the location of the field where the date has been entered.

{ 
    "CustomFieldDefinitionId": "d4324297-975e-490e-914b-ae562765ec5b",
    "EntityId": "163a633d-8180-4a65-8c32-1818aa14126d", 
    "Id": "f0ab99b3-2c05-4030-b456-00b50b3d1c81", 
    "Date": "2019-07-21T19:00:00" 
}

Notes

/Notes
/'entity' $expand Notes

On the Note entries the ‘TrackTypeId’ is referencing a DropDown Value corresponding to the ‘Activity Type’. The Text of the note will include non-printable characters to represent line feeds and carriage returns.

Contacts, Companies, and Opportunities are the only entities which will have Notes associated with them.

{ 
    "UserId": "a3c0f07e-e99e-488a-b15b-f18ff2d855b0", 
    "EntityId": "cd460b9c-c757-4301-a06b-2a8a506d7277", 
    "CreatedDate": "2020-02-04T18:31:06.173", 
    "TrackId": "867205f2-093f-4ac8-b234-0924275c2636", 
    "TrackTypeId": "999ae731-d916-47df-ae4c-1dc197387155", 
    "Text": "----------- 2/4/2020 6:31 PM (UTC-08:00) - Modified by: Mark Foltz ----------- Activity\r\nSuperSonics Opportunity created\r\nCompany: The Walt Disney Company\r\nContact(s): Walt Disney, Robert Iger, Luc Skywalker", 
    "Id": "f3229086-b8ea-45a8-95d2-00832aa212f3" 
}

Products

/Products
/ProductGroups
/OpportunityProducts

Addresses

/Addresses

API Examples

Creating Entities

Creating entities is executed with a POST call. Most newly created entities are then linked to other entities or custom fields with a PUT (ex. Contact is linked to a User and/or Custom Fields).

Method = POST
Success = 201

To create an entity POST the entity to URL's.
/Contacts
/Companies
/Opportunities
/Notes
/CustomFieldValueTexts
/CustomFieldValueDates
/CustomFieldValueDropdowns
/Addresses

Example 1: To create a Company, include all the fields of a company record that in the GET method, also need to supply a new GUID for the new record. If link to an existing Contact, put the contact ID in PrimaryContactId, otherwise leave it null.

Example 2: To create a new Contact, include all the fields of a contact record that in the GET method. If the Company does not exists, create one and put its Id in MainCompanyId:

Linking Entities

Method = PUT
Success = 203

To link entities send a PUT: (Example links a Contact to a User)

URL: 
/Contacts(guid'${contactId}')/$links/AssignedUsers Body:  <uri xmlns="http://schemas.microsoft.com/ado/2007/08/dataservices"> https://prophetOnDemand.com/prophet/prophetwebservices/AvtProphetApi/odata/Users(guid'userId') </uri> Commonly Linked Entities: Contacts/Companies/Opportunities -> User (AssignedUsers) Contacts/Companies/Opportunities -> CustomFields Contacts/Companies/Opportunities -> Addresses Companies/Opportunities -> Contacts (AssignedContacts) Contacts/Opportunities -> Companies (AssignedCompanies) Contacts/Companies -> Opportunities (AssignedOpportunities) Notes -> Contacts/Companies/Opportunities

Contacts/Companies/Opportunities can be linked to multiple Users, Custom Fields, and Notes.

Users can be linked to multiple Contacts/Companies/Opportunities.

Contacts can be linked to multiple Opportunities, but only one Company. Contacts can be linked to one company, must have the Company Id in the “MainCompanyId” as well as be linked.

Companies can be linked to multiple Contacts and multiple Opportunities. They may only have two addresses, a Primary Address and a Shipping Address.

Opportunities can be linked to multiple Contacts from various companies. Opportunities may only be linked to one Company, and must have the Company’s Id in the “MainCompanyId” field.

Checking Entities

Method = GET 
Success = return the latest Contact that match the conditions

To check if Contact exists based on "First Name/Last Name/Email or First Name/Last Name/Business Phone":
URL:
/Contacts?$filter=(Email%20eq%20'YourUrlEncodedEmail' and FirstName%20eq%20'YourUrlEncodedFirstName'%20and%20LastName%20eq%20'YourUrlEncodedFirstName')%20or%20(FirstName%20eq%20'YourUrlEncodedFirstName'%20and%20LastName%20eq%20'YourUrlEncodedFirstName'%20and%20BusinessPhone%20eq%20'YourUrlEncodedBusinessPhone')&$top=1&$orderby=UpdatedDate%20desc

To check if Company exists based on "Company Name":
URL:
/Companies?$filter=Name%20eq%20'YourUrlEncodedCompanyName'&$top=1&$orderby=UpdatedDate%20desc

Updating Entities

Method = PUT
Success = 204

To update a Contact, need every field and its value from the GET method and specify the contact ID in the URL.
URL: /Contacts(GUID'00000100-0000-0000-0000-000000000221')

To update a Company, need every field and its value from the GET method. If link to an existing Contact, put the contact ID in PrimaryContactId
URL: /Companies(GUID'00000000-0000-0000-0000-000000000111')

Deleting Entities

Method = DELETE
Success = 204

To delete an entity, send a DELETE URL without body :
URL: /Companies(GUID'00000000-0000-0000-0000-000000000111')