MiniCRM API

Basics

By using MiniCRM API, other softwares can access and modify data stored in MiniCRM. You can create new Apps or integrate existing ones.

It’s a simple REST/Json API that is easily accessible from many languages (Javascript, PHP, C#, C, Java, etc.). To use MiniCRM API you need an active account and an API key.

Authentication is implemented with “HTTP Auth” over HTTPS/SSL.

To authorize requests, you need:

System ID (SystemId)
API key (APIKey)

To create API key, go to the Settings > System page and click on the Create new API key button. If you have already created a key, here you can a generate a new one later or delete the existing one.

api

MiniCRM API Url:

https://SystemId:APIKey@r3.minicrm.io/Api/R3

PHP Developers can use our MiniCRM API PHP client that provides an object-oriented interface. To download the API client and example codes, click here:

https://cdn.minicrm.hu/media/example-en

Character Encoding

MiniCRM API uses UTF-8 codepage for all input and output.

Data format

All input and output data is structured according to JSON standard.

Services

Modules

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Category

This endpoint returns all available modules with their respective IDs.

Example output:

{
  "3": "Sales",
  "5": "Support",
  "6": "Projects",
  "8": "Invoicing"
}

Modules with details

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Category?Detailed=1

This endpoint returns all available modules with their respective IDs and basic settings.

Example output:

{
    "3": {
        "Id": 1,
        "OrderId": 1,
        "Name": "Sales",
        "Type": "Generic",
        "SenderName": "Test User",
        "SenderEmail": "test.user@minicrm.local",
        "Phone": 36201234567
    },
    "5": {
        "Id": 2,
        "OrderId": 3,
        "Name": "Support",
        "Type": "HelpDesk",
        "SenderName": "Test User",
        "SenderEmail": "test.user@minicrm.local",
        "Phone": ""
    },
    "6": {
        "Id": 3,
        "OrderId": 5,
        "Name": "Projects",
        "Type": "Generic",
        "SenderName": "Test User",
        "SenderEmail": "test.user@minicrm.local",
        "Phone": ""
    },
    "8": {
        "Id": 8,
        "OrderId": 4,
        "Name": "Invoicing",
        "Type": "Invoice",
        "SenderName": "Test User",
        "SenderEmail": "test.user@minicrm.local",
        "Phone": 36301234567
    }
}

Database Schema

Example:

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Schema/Business

MiniCRM is a customizable application. Every company is different so every CRM instance is different. To know which fields and possible values are present in a given system, you can use the Schema API to download available fields. There are 3 entity types: Project, Business, Person. Project scheme depends on the module so you need to specify which module’s project scheme you are interested in.

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Schema/Project/3

Field types:

CategoryId: Module ID (eg. 3)
ContactId: Contact ID (eg. 12345)
StatusId: Status in sales/workflow pipeline (eg. 2500 or ‘VIP Customer’)
UserId: User ID or user name (eg. 3200 or ‘John Doe’)
BusinessId: Company ID (eg. 12345)
Deleted: 0 or 1 (1 indicating that the entity is trashed)
Int: 64 bit signed integer (eg. 125)
Text: 1024 characters long string (some specific fields can have shorter/longer limits)
DateTime: Date & time field (eg. ‘2013-05-25 13:12:00’)
File: An URL pointing to the file you’d like to upload (eg. ‘https://www.minicrm.hu/tesztfajl.xls’)
Enum: Enum field, can be set by Id or Text value (eg. 1740 or ‘Qualified’)
Set: Multiple choice field, can be set with bitmask or text values seperated by comma. (eg. 6 or ‘Second choice,Third choice’)

Example result:

{
  "Id": "Int",
  "CategoryId": {
    "3": "Sales",
    "5": "Support",
    "6": "Projects",
    "8": "Invoicing"
  },
  "ContactId": "Int",
  "StatusId": {
    "2509": "Contacted",
    "2500": "In progress",
    "2512": "Contracting",
    "2540": "Customer"
  },
  "UserId": {
    "3200": "John Doe",
  },
  "Name": "Text(128)",
  "Deleted": "Boolean",
  "Int1107": "Int",
  "DateTime1106": "DateTime",
  "File1113": "File(10MB)",
  "Text1105": "Text(1024)",
  "Referrer": {
    "1253": "Cold Call",
    "1254": "WOM",
    "1255": "Google",
    "1340": "Other"
  },
  "Qualification": {
    "1328": "Qualified (Ideal)",
    "1329": "Qualified",
    "1330": "Unqualified"
  },
  "Set1035": {
    "1": "First choice",
    "2": "Second choice",
    "4": "Third choice"
  }
}

Searching

The property Count contains the number of search results. The property Results has hits in array, using ID as a key. Search results contain basic information about the found entities. Use the Url field to access all details through API. One page contains 100 results. You can request further hits using the Page parameter:

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?Query=Test&Page=1

Paging starts at 0 so the second page can be accessed with Page=1.

Project search (full-text)

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?Query=Test

Example output:

{
  "Count": 1,
  "Results": {
    "1234": {
      "Id": "1234",
      "Name": "Test project",
      "Url": "https://r3.minicrm.hu/Api/R3/Project/1234",
      "StatusId": "2500",
      "UserId": "3200",
      "Deleted": "0"
    }
  }
}

Project search (field-based)

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?StatusId=2500&UserId=3200

UpdatedSince parameter helps you to find entities that were updated recently (e.g. since your last sync).

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?StatusId=2500&UpdatedSince=2013-03-01+12:00:00

StatusGroup parameter can be used to search for projects in a specific stage in the pipeline (Open, Success, Failed).

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?StatusGroup=Success

Example output:

{
  "Count": 1,
  "Results": {
    "1234": {
      "Id": "1234",
      "Name": "Test project",
      "Url": "https://r3.minicrm.hu/Api/R3/Project/1234",
      "StatusId": "2500",
      "UserId": "3200",
      "Deleted": "0"
    }
  }
}

Project (GET)

Projects can be identified by MiniCRM’s internal ID (ProjectId) or an external ID provided by you when adding data (ReferenceId).

ProjectId:

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project/1234

ReferenceId:

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project?ReferenceId=123456

Example output:

{
  "Id": 1234,
  "CategoryId": 3,
  "ContactId": 12345,
  "StatusId": "Contacted",
  "UserId": "John Doe",
  "Name": "Very Motivated Customer",
  "Deleted": "0",
  "LeadSource": "WOM",
  "InterestedIn": "Premium products",
  "Text1105": "Lorem ipsum....",
  "Int1107": 12500,
  "File1103": "https://cdn.minicrm.hu/doc/2013/04-25/A/Q/AQFwQq7Os0kE5ykH_GSJfg-1"
}

Project (PUT)

When modifying existing projects, it’s always best to send only the changed fields:

$ curl -XPUT https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Project/1234 -d '{
 "Name":"New name given through API",
 "Deleted":"1"
}'

If you omit the ID parameter from the URL, MiniCRM will create a new entity in the DB. The CategoryId and ContactId fields are required for new projects. They can’t be updated for existing projects.

You can use the ReferenceId field to pass along the entity ID used in your application.

Example output:

{
  "Id":1234
}

Contact Search (full-text)

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Contact?Query=John

If you want to look up contacts with a specific phone number, please use numbers only. You have to provide at least the last 6 digits of the phone number.

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Contact?Query=2345678

Example output:

{
  "Count": 1,
  "Results": {
    "12345": {
      "Id": "12345",
      "Name": "John Doe",
      "Url": "https://r3.minicrm.hu/Api/R3/Contact/12345",
      "Type": "Person",
      "Email": "jd@example.com",
      "Phone": "0612345678"
    }
  }
}

Contact Search (field-based)

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Contact?Email=jd@example.com&Type=Person

Example output:

{
  "Count": 1,
  "Results": {
    "12345": {
      "Id": "12345",
      "Name": "John Doe",
      "Url": "https://r3.minicrm.hu/Api/R3/Contact/12345",
      "Type": "Person",
      "Email": "jd@example.com",
      "Phone": "0612345678"
    }
  }
}

Contact (GET)

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Contact/12346

Example output (Company):

{
  "Id": 12346,
  "Type": "Business",
  "Name": "Test Business",
  "Email": "info@test.com",
  "EmailType": "",
  "Phone": "06-1 / 987-65432",
  "PhoneType": "",
  "Description": "",
  "Url": "http://test.com",
  "Industry": "",
  "Region": "",
  "VatNumber": "",
  "RegistrationNumber": "",
  "BankAccount": "12345678-12345678-12345678",
  "Swift": "",
  "Employees": 0,
  "YearlyRevenue": 0
}

Example output (Person):

{
  "Id": 12345,
  "BusinessId": 12346,
  "Type": "Person",
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "jd@example.com",
  "EmailType": "",
  "Phone": "0612345678",
  "PhoneType": "",
  "Position": "IT"
}

Contact (PUT)

When modifying existing projects, it’s best to send only the changed fields:

$ curl -XPUT https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Contact/12345 -d '{
 "FirstName":"John",
 "LastName":"Doe"
}'

If you omit the ID parameter from the URL, MiniCRM will create a new contact.

You can use the field ReferenceId to pass along the entity ID used in your application.

Example output:

{
  "Id":12345
}

Task Search

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/ToDoList/1234?Status=Open

You can download all tasks belonging to a project. You can filter by Status. Possible values are: Open, Closed and All.

Example output:

{
   "Count":2,
   "Results":[
      {
         "Id":"1111",
         "Status":"Open",
         "Comment":"Do something.",
         "Deadline":"2012-01-17 23:59:00",
         "UserId":"3200",
         "Type":"0",
         "Url":"https://r3.minicrm.hu/Api/R3/ToDo/1111"
      },
      {
         "Id":"2222",
         "Status":"Open",
         "Comment":"Do something else.",
         "Deadline":"2013-01-22 23:59:00",
         "UserId":"3300",
         "Type":"1566",
         "Url":"https://r3.minicrm.hu/Api/R3/ToDo/2222"
      }
   ]
}

Task (GET)

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/ToDo/1111

Example output:

{
   "Id":1111,
   "UserId":"John Doe",
   "ProjectId":2001,
   "Type":"",
   "Status":"Open",
   "Deadline":"2012-01-17 23:59:00",
   "Comment":"Do something.",
   "Attachments":{
      "FileName":"details.pdf",
      "Url":"https://cdn.minicrm.hu/doc/2013/04-25/A/Q/AQFwQq7Os0kE5ykH_GSJfg-1"
   }
}

Task (PUT)

$ curl -XPUT https://SystemId:APIKey@r3.minicrm.hu/Api/R3/ToDo/1111 -d '{
 "Comment":"Do something more.",
 "Deadline":"2013-01-25 13:30:00"
}'

Example output:

{
  "Id":1111
}

Address (List)

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/AddressList/1234

Get all addresses of a given Contact (ContactId).

Example output:

{
   "Count":2,
   "Results":[
      {
         "123":"Home address (5555 Walrand 66 Chrissundra Street)",
         "456":"Office address (4444 Lap 197 Mazen Street)"
      }
   ]
}

Address (GET)

$ curl https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Address/123

Example output:

{
   "Id":123,
   "ContactId":1234,
   "Type":"HQ",
   "Name":"MiniCRM Ag.",
   "CountryId":"Hungary",
   "PostalCode":5555,
   "City":"Budapest",
   "Address":"Well Known street 1.",
   "Default":1
}

Address (PUT)

$ curl -XPUT https://SystemId:APIKey@r3.minicrm.hu/Api/R3/Address/123 -d '{
   "Address":"Well Known street 2.",
}'

Example output:

{
  "Id":123
}

Error handling

MiniCRM uses HTTP return codes. 200 - OK means that the request was successful. In case of errors the output is a plain text error message, not a Json object.

Error codes:

400 - Bad Request: The request contains illegal or missing parameters. Resubmitting the same request will produce the same error.
404 - Not Found: Requested entity not found (wrong ID).
405 - Method Not Allowed: The endpoint doesn’t support the request method. E.g.: you are trying to send PUT request to a read-only endpoint.
500 - Internal Server Error: Something went wrong on our side. The error has been logged, we will try to fix it ASAP. It could have been a temporal error, resubmitting the request might solve the problem.

Examples

In this section, some example API programs will be shown, using Curl.

Example searching (GET):

SystemID: 50
API key: ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1
Project we want to find: Test Project

//Creating the URL
$Url = 'https://50:ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1@r3.minicrm.hu/Api/R3/Project?Query=Test Project';

//Initializing the Curl
$Curl = curl_init();
curl_setopt($Curl, CURLOPT_RETURNTRANSFER , true);
curl_setopt($Curl, CURLOPT_SSL_VERIFYPEER , false);

//Handover the URL to the Curl
curl_setopt($Curl, CURLOPT_URL, $Url);

//Execute the Curl request
$Response = curl_exec($Curl);

//Check for any errors in the Curl request
if(curl_errno($Curl)) $Error = "Hiba a Curl futtatásakor: ".curl_error($Curl);

//Request for the HTML response code
$ResponseCode = curl_getinfo($Curl, CURLINFO_HTTP_CODE);
if($ResponseCode != 200) $Error = "API error code: {$ResponseCode} - Message: {$Response}";

//Closing the Curl
curl_close($Curl);

//Decoding and exporting the JSON response
$Response = json_decode($Response, true);
var_export($Response);

Example for downloading (GET):

SystemID: 50
API key: ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1
ID of the project we want to download: 12345

//Creating the URL
$Url = 'https://50:ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1@r3.minicrm.hu/Api/R3/Project/12345';

//Initializing the Curl
$Curl = curl_init();
curl_setopt($Curl, CURLOPT_RETURNTRANSFER , true);
curl_setopt($Curl, CURLOPT_SSL_VERIFYPEER , false);

//Handover the URL to the Curl
curl_setopt($Curl, CURLOPT_URL, $Url);

//Execute the Curl request
$Response = curl_exec($Curl);

//Check for any errors in the Curl request
if(curl_errno($Curl)) $Error = "Hiba a Curl futtatásakor: ".curl_error($Curl);

//Request for the HTML response code
$ResponseCode = curl_getinfo($Curl, CURLINFO_HTTP_CODE);
if($ResponseCode != 200) $Error = "API Hibakód: {$ResponseCode} - Üzenet: {$Response}";

//Closing the Curl
curl_close($Curl);

//Decoding and exporting the JSON response
$Response = json_decode($Response, true);
var_export($Response);

Example for uploading (PUT):

SystemID: 50
API key: ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1
Project datas we want to upload:
- Project name: First Project
- Project assignee: Peter Test (UserID: 3200)
- Project status: Qualified Prospect (StatusID: 2500)
- ModuleID (Required for every new project): 3
</ul> //Creating the URL $Url = 'https://50:ZxPPCqDItuQhoaLeBM2679mT3iG5NgH1@r3.minicrm.hu/Api/R3/Project'; //Creating the array for the parameters $Params = array( 'Name' => 'Első API projekt', 'UserId' => 3200, 'StatusId' => 2500, 'CategoryId' => 3 ); //Initializing the Curl $Curl = curl_init(); curl_setopt($Curl, CURLOPT_RETURNTRANSFER , true); curl_setopt($Curl, CURLOPT_SSL_VERIFYPEER , false); //Encoding the array to JSON $Params = json_encode($Params); //Setting up the headers (Content type, lenght and character encoding) curl_setopt($Curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json','Content-Length: '.strlen($Params), 'charset=UTF-8')); //Setting the Curl request type to PUT curl_setopt($Curl, CURLOPT_CUSTOMREQUEST, "PUT"); //Handover the array to the Curl curl_setopt($Curl, CURLOPT_POSTFIELDS, $Params); //Handover the URL to the Curl curl_setopt($Curl, CURLOPT_URL, $Url); //Executing the Curl request $Response = curl_exec($Curl); //Check if any error occurred during the request if(curl_errno($Curl)) $Error = "Error: ".curl_error($Curl); //Request for the HTML response code $ResponseCode = curl_getinfo($Curl, CURLINFO_HTTP_CODE); if($ResponseCode != 200) $Error = "API error code: {$ResponseCode} - Message: {$Response}"; //Closing the Curl curl_close($Curl);