Skip to main content
Skip table of contents

CRM API

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.  ⚠️ 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

Action

Command Value

Description & Command Example

Get companies

getcompanies

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

Example:

  • getcompanies

Response Example

CODE 
"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"
	}
]

Get a company

getcompanybyname

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

CODE 
"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"

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

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

Update a company

editcompany

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

CODE 
"success": true,
"details":"company has been edited"

Delete a company

deletecompany

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

Example:

  • deletecompany&companyName=Apitest

Response Example

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

Get contacts

getcontacts

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

Example:

  • getcontacts

Response Example

CODE 
"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" : ""
	}
]

Get a contact

getcontactbyname

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

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

Create a contact

addcontact

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

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

Update a contact

editcontact 

Requires Edit contacts permissions.

Update a contact attribute value using by its id.

Example:

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

Response Example

CODE 
"success": true,
"details":"contact has been edited"

Update a contact – link to an existing Company

setcontact

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

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

Delete a contact

deletecontact

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

Example:

  • deletecontact&contactName=Lucy

Response Example

CODE 
"success": true,
"details":"contact has been removed"

Create a custom directory entry

adddictionaryvalue

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

CODE 
"success": true,
"details":"new value has been added to the dictionary"

Delete a custom directory entry

removedictionaryvalue

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

Example:

  • removedictionaryvalue&dictionaryName=Positions&valuetoremove=architect

Response Example

CODE 
"success": true,
"details":"the value has been removed from the dictionary"

Get entries by attributes' values

searchEntities

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

CODE 
"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

Get transactions

transactionsList

Gets the list of CRM transactions with their parameters.

Example:

  • transactionslist

Response Example

CODE 
"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
	}

Updates a CRM Property custom field

setcrmproperties

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

Example:

  • setcrmproperties&issueId=10600

Response Example

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

Start synchronization process

sync

Starts synchronization of JIRA users and CRM contacts.

Example:

  • sync

Response Example

CODE 
"success": true,
"details":"sync process started"

Create/Update a directory entry

updateOrCreateEntity

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

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

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
CODE 
[{"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}]

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"}


Entry ID

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

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close