Overview

The CRM API is used to interact with the CRM for Jira application remotely, for example when synchronizing companies and contacts with other systems.

Base URL & Call Structure

Each CRM API call has the same structure, like the following:

YOUR_JIRA_ADRESS/plugins/servlet/crm/api?apiKey=apiKey&userName=userName&command=command

where:

  • apiKey – determines the identity of the caller. This parameter accepts the Key specified for the CRM app on a particular instance in CRM Administration → Integrations → Access API.
  • userName – determines which actions the caller can take. This parameter accepts the login of a Jira user. (warning) Note that Jira permissions and CRM permissions of the user are taken into account.
  • command – determines the required action. See the list of available commands below.

Available Commands

ActionCommand ValueDescription & Command Example
Get companiesgetcompanies

Gets the list of companies with all their attributes. No extra parameters required.

Example:

  • getcompanies

Response Example

"success": true,
"companies" : [
	{
	"id" : "1" ,
	"clients_field_16f2eb8c-3620-42dd-ac8c-1a643c1612a4" : "Approved" ,
	"name" : "Garry's" ,
	"org_type" : "Lead"
	},
	{
	"id" : "2" ,
	"clients_field_16f2eb8c-3620-42dd-ac8c-1a643c1612a4" : "Approved" , 
	"name" : "Reccurence LTD" ,
	"org_type" : "Competitor"
	}
]
CODE
Get a companygetcompanybyname

Gets a company with all its attributes by its name or ID. Requires one of the following parameters: companyId or companyName.

Examples:

  • getcompanybyname&companyId=48
  • getcompanybyname&companyName=apitest

Response Example

"success": true,
"id" : "48" ,
"org_name" : "apitest" ,
"org_type" : "Lead" ,
"org_industry" : "" ,
"org_www" : "" ,
"clients_field_8eae4416-7a3d-49f2-8ab4-640898bff92d" : "Unsupported" ,
"org_contact" : "" ,
"org_people" : "Unsupported"
CODE

Create a company


addcompany

Adds an entry in the list of CRM Companies. The required company attributes should be specified as additional parameters.

The existing values cannot be set if the attribute is unique.

Example:

  • addcompany&clients-org_name=Teamlead&clients-org_type=1

Response Example

"success": true,
"details": "company has been added",
"id": "56"
CODE
Update a companyeditcompany

Update a company attribute value using by its id or name.

Example:

  • editcompany&companyId=51&clients_field_d1facd51-01e0-4a68-a4f3-4aa3641a590e=Development
  • editcompany&companyId=51&Сompany%20Name=Oliva

Response Example

"success": true,
"details":"company has been edited"
CODE
Delete a companydeletecompany

Delete the specified entry from the companies directory. Requires the following parameter: companyName.

Example:

  • deletecompany&companyName=Apitest

Response Example

"success": true,
"details":"company has been removed"
CODE
Get contactsgetcontacts

Get the list of contacts with all their attributes.  No extra parameters required.

Example:

  • getcontacts

Response Example

"success": true,
"contacts" : [
	{
	"id" : "1" ,
	"contact_company" : "Oxi" ,
	"contact_name" : "Kelly Dorn" ,
	"contact_position" : "" ,
	"contacts_field_2a7753d6-2179-42ff-95f2-ecd2dd90ed13" : ""
	},
	{
	"id" : "2" ,
	"contact_company" : "JustiCo ",
	"contact_name" : "Alan Lemon" ,
	"contact_position" : "" ,
	"contacts_field_2a7753d6-2179-42ff-95f2-ecd2dd90ed13" : ""
	}
]
CODE
Get a contactgetcontactbyname

Requires Access to main menu CRM permissions.

Gets the contact with all its attributes by its name or ID. Requires one of the following parameters: contactID or contactName.

Examples:

  • getcontactbyname&contactId=33
  • getcontactbyname&contactName=Kelly%20Dorn

Response Example

"success": true,
"id" : "33" ,
"contacts_field_2a7753d6-2179-42ff-95f2-ecd2dd90ed13" : "" ,
"contact_name" : "Kelly Dorn" ,
"contact_company" : "Oxi" ,
"contact_position" : ""
CODE
Create a contactaddcontact

Adds an entry in the list of CRM Contacts. The required contact attributes should be specified as additional parameters.

The existing values cannot be set if the attribute is unique.

Example:

  • addcontact&clients-contact_name=Andy&clients-contact_position=Manager

Response Example

"success": true,
"details": "contact has been added",
"id": "194"
CODE
Update a contacteditcontact 

Requires Edit contacts permissions.

Update a contact attribute value using by its id.

Example:

  • editcontact&contactName=Kelly%20Dorn&contacts_field_2a773=1234567

Response Example

"success": true,
"details":"contact has been edited"
CODE
Update a contact – link to an existing Companysetcontact

Includes a contact to an existing company. Requires the following parameters: companyName/companyId and contactName/contactID

Example:

  • setcontact&companyName=apitest&contactName=Kelly%20Dorn
  • setcontact&companyId=15&contactID=135

Response Example

"success": true,
"details":"company apitest set for contact Kelly Dorn"
CODE
Delete a contactdeletecontact

Delete the specified entry from the contacts directory. Requires the following parameters: contactName.

Example:

  • deletecontact&contactName=Lucy

Response Example

"success": true,
"details":"contact has been removed"
CODE
Create a custom directory entryadddictionaryvalue

Adds an entry to a speified custom directory. Requires the following parameters: dictionaryName and newvalue (becomes a name o the entry)

Example:

  • adddictionaryvalue&dictionaryName=Positions&newvalue=architect

Response Example

"success": true,
"details":"new value has been added to the dictionary"
CODE
Delete a custom directory entryremovedictionaryvalue

Delete the specified entry from the specified custom directory. Requires the following parameters: dictionaryName and valuetoremove.

Example:

  • removedictionaryvalue&dictionaryName=Positions&valuetoremove=architect

Response Example

"success": true,
"details":"the value has been removed from the dictionary"
CODE
Get entries by attributes' valuessearchEntities

Get CRM objects by parameters. Requires tableName and the attribute – value pairs (crm_param_1=attribute&crm_param_1_value=value)

Example:

  • searchEntities&tableName=CONTACTS&crm_param_1=Company&crm_param_1_value=Oxi

Response Example

"success": true,
"records": [
	{
	"id" : "33" ,
	"contact_company": "Oxi" ,
	"contact_name": "Kelly Dorn" ,
	"contact_position": "" ,
	"contacts_field_2a7753d6-2179-42ff-95f2-ecd2dd90ed13": "1234567" ,
	"contacts_field_db52cdf2-aac6-4d05-b264-28f2c0b9a489": "true" ,
	"name": "Kelly Dorn"
	}
],
"count": 1
CODE
Get transactions

transactionsList

Gets the list of CRM transactions with their parameters.

Example:

  • transactionslist

Response Example

"success":true,
"records":{
	"userdata":{
		"allSum":"57,723",
		"allSumVal":"57723"
		},
	"total":"1",
	"records":"2",
	"tranRemovePerm":true,
	"page":"1",
	"tranEditRecordPerm":true,
	"tranExportPerm":true,
	"rows":[
		{
		"companyId":"49",
		"companyName":"Reccurence LTD",
		"id":"8",
		"cell":[
			"SUP-116",
			"Reccurence LTD",
			"123",
			"Income",
			"2/Jan/20",
			"123",
			"Plan"
			],
		"direction":"debet"
		},
		{
		"companyId":"42",
		"companyName":"Teamlead",
		"id":"7",
		"cell":[
			"",
			"Teamlead",
			"Jira SD",
			"Income",
			"30/Oct/19",
			"21,000",
			"Fact"
			],
		"direction":"debet"
		},
	],
	"tranFormView":true,
	"alwaysShowDecimalPart":false
	}
CODE
Updates a CRM Property custom fieldsetcrmproperties

Updates a specified field of the CRM Property type. Requires issueId (custom field ID)

Example:

  • setcrmproperties&issueId=10600

Response Example

"success": true,
"details":"setCrmProperties done"
CODE


Start synchronization processsync

Starts synchronization of JIRA users and CRM contacts.

Example:

  • sync

Response Example

"success": true,
"details":"sync process started"
CODE
Create/Update a directory entryupdateOrCreateEntity

Creates or updates an entity in the specified directory. Requires tableName and the attribute – value pairs (crm_param_1=attribute&crm_param_1_value=value)

Example:

  • updateOrCreateEntity&tableName=PRODUCTS&crm_param_1=Product%20Name&crm_param_1_value=Test

Response Example

"success": true,
"details":"new record has been added"
CODE

Common Errors

Invalid API key

{"success": false, "details":"Invalid apikey!"}

Caller not found

{"success": false, "details":"User username can not be found!"}

Missed parameters

{"success": false, "details":"userName, apiKey and command parameters are required!"}
Either authentification, authorization or command are not specified.

{"success": false, "details":"parameter or parameter parameters are required!"}
One or several of the required parameters are not specified.

Non-existing command

{"success": false, "details":"only sync, getcompanies, addcompany, getcompanybyname, editcompany, deletecompany, getcontacts, addcontact, getcontactbyname, editcompany, deletecontact, setcontact, unsetcontact, setcrmproperties, adddictionaryvalue, searchEntities, editcontact, transactionslist commands allowed"}

No such entry

{"success": false, "details":"entry can not be found!"}

Duplicative value

{"success": false, "details":[{"fieldCode":"fieldcode","errorMessage":"This value is already in use"},{"fieldCode":"fieldcode","errorMessage":"This value is already in use"}]}
The attribute value that should be unique already exists.

Not enough permissions

{"success": false, "details":"To access this resource user need "sample_permissions" permissions."}

Find Table Names, Attribute Codes, etc.

Table Names

The following table names are available for the standard CRM Directories:

  • CLIENTS

  • CONTACTS

  • PRODUCTS

  • TRANSACTIONS

  • BUDGET

As for the custom directories, you can check the table name as following:

List of Table Attributes

To get the list of particular table attributes' name (no codes), perform the following call:

YOUR_JIRA_ADDRESS/rest/admin_rest/1.0/fields/TABLENAME/fieldsList

 Response Example
[{"isinorder":false,"tab":12,"isdisabled":null,"name":"Phone","show":false,"isreadonly":false,"disabled":null,"id":47,"nameen":"Phone","type":"phone","required":false},{"isinorder":false,"tab":12,"isdisabled":null,"name":"Full Name","show":true,"isreadonly":false,"disabled":null,"id":28,"nameen":"Full Name","type":"strng","required":true},{"isinorder":false,"tab":12,"isdisabled":null,"name":"Company","show":true,"isreadonly":false,"disabled":null,"id":25,"nameen":"Company","type":"org","required":true},{"isinorder":false,"tab":12,"isdisabled":null,"name":"Position","show":true,"isreadonly":false,"disabled":null,"id":29,"nameen":"Position","type":"dic","required":false},{"isinorder":false,"tab":12,"isdisabled":null,"name":"JIRA login","show":false,"isreadonly":true,"disabled":null,"id":27,"nameen":"JIRA login","type":"strng","required":false},{"isinorder":false,"tab":12,"isdisabled":null,"name":"E-Mail","show":true,"isreadonly":false,"disabled":null,"id":26,"nameen":"E-Mail","type":"eml","required":false},{"isinorder":false,"tab":12,"isdisabled":null,"name":"Active","show":true,"isreadonly":false,"disabled":null,"id":92,"nameen":"Active","type":"chckbx","required":false}]
CODE

Attribute Code

To get the attributes' codes and values for the particular entry, perform the following call:

YOUR_JIRA_ADDRESS/rest/catalog-rest/1.0/catalog/getNomDetails?nomId=ENTRY_ID&tableName=TABLENAME

 Response Example
{"companiesViewPerm":true,"tranPerm":true,"addPerm":true,"removePerm":true,"editRecordPerm":true,"locale":"en","readonly":false,"fields":[{"id":28,"isName":true,"isLogin":false,"isRequired":true,"code":"contact_name","valuesRu":"","tableName":"CLIENTS","nameRu":"Full Name","type":"strng","tabCode":"contact_main","width":200,"visible":"false","value":"","selectValue":"","isReadonly":false,"dictionaryType":"","values":[]},{"id":25,"isName":false,"isLogin":false,"isRequired":true,"code":"contact_company","valuesRu":"","tableName":"CLIENTS","nameRu":"Company","type":"org","tabCode":"contact_main","width":200,"visible":"false","value":"","selectValue":"","isReadonly":false,"dictionaryType":"","values":[]},{"id":29,"isName":false,"isLogin":false,"isRequired":false,"code":"contact_position","valuesRu":"","tableName":"CLIENTS","nameRu":"Position","type":"dic","tabCode":"contact_main","width":200,"visible":"false","value":"","selectValue":"","isReadonly":false,"dictionaryType":"Positions","values":[{"code":"67","value":"Support Manager"},{"code":"68","value":"Developer"},{"code":"64","value":"Analyst"},{"code":"65","value":"CEO"},{"code":"66","value":"Tester"},{"code":"93","value":"43"},{"code":"63","value":"Project Manager"},{"code":"90","value":"1"},{"code":"91","value":"2"},{"code":"92","value":"3"},{"code":"94","value":"56"},{"code":"95","value":"3445"}]},{"id":26,"isName":false,"isLogin":false,"isRequired":false,"code":"contact_email","valuesRu":"","tableName":"CLIENTS","nameRu":"E-Mail","type":"eml","tabCode":"contact_main","width":200,"visible":"false","value":"","selectValue":"","isReadonly":false,"dictionaryType":"","values":[]},{"id":27,"isName":false,"isLogin":true,"isRequired":false,"code":"contact_login","valuesRu":"","tableName":"CLIENTS","nameRu":"JIRA login","type":"strng","tabCode":"contact_main","width":200,"visible":"true","value":"","selectValue":"","isReadonly":true,"dictionaryType":"","values":[]},{"id":47,"isName":false,"isLogin":false,"isRequired":false,"code":"contacts_field_2a7753d6-2179-42ff-95f2-ecd2dd90ed13","tableName":"CLIENTS","nameRu":"Phone","type":"phone","tabCode":"contact_main","width":200,"visible":"true","value":"","selectValue":"","isReadonly":false,"values":[]},{"id":92,"isName":false,"isLogin":false,"isRequired":false,"code":"contacts_field_db52cdf2-aac6-4d05-b264-28f2c0b9a489","tableName":"CLIENTS","nameRu":"Active","type":"chckbx","tabCode":"contact_main","width":200,"visible":"false","value":"","selectValue":"","isReadonly":false,"values":[]}],"fieldsTabs":[{"id":12,"code":"contact_main","name":"Main"}],"dateFormat":"%e/%b/%y","past90start":"07/May/20","past90end":"05/Aug/20","past30start":"06/Jul/20","past30end":"05/Aug/20","monthstart":"01/Aug/20","monthend":"31/Aug/20","lastmonthstart":"01/Jul/20","lastmonthend":"31/Jul/20","thisquarterstart":"01/Jul/20","thisquarterend":"30/Sep/20","lastquarterstart":"01/Apr/20","lastquarterend":"30/Jun/20","thisyearstart":"01/Jan/20","thisyearend":"31/Dec/20","lastyearstart":"01/Jan/19","lastyearend":"31/Dec/19","recordId":"47","q1start":"01/Jan/20","q1end":"31/Mar/20","q2start":"01/Apr/20","q2end":"30/Jun/20","q3start":"01/Jul/20","q3end":"30/Sep/20","q4start":"01/Oct/20","q4end":"31/Dec/20"}
CODE


Entry ID

To find an entry ID open it in the full mode: