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](https://d26cfm2pfnephr.cloudfront.net/uploads/2015/07/new_api.jpg) 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://bitbucket.org/minicrm/api-php-client-r3-phar/get/tip.zip](https://bitbucket.org/minicrm/api-php-client-r3-phar/get/tip.zip) ### 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": "http://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@APIKeyr3.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":"http://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.