Python scripts

On this page we explain how to programmatically interact with EspoCRM in Python. We use the EspoCRM API, and in particular the API Client implementation in Python.

What is Python?

Python is a high-level programming language with a simple syntax, which makes it easily readable and extremely user-friendly. It is commonly used to build websites and software, automate tasks, and conduct data analysis.

Why Python?

• It’s easy to read. Python code uses English keywords rather than punctuation, and its line breaks help define the code blocks. In practice, this means you can identify what the code is designed to do simply by looking at it.
• It’s open source. You can download the source code, modify it, and use it however you want.
• It’s portable. Some languages require you to modify code to run on different platforms, but Python is a cross-platform language, which means you can run the same code on any operating system with a Python interpreter.
• It’s extendable. Python code can be written in other languages (such as C++), and users can add low-level modules to the Python interpreter to customize and optimize their tools.
• It has a broad standard library. This library is available for anyone to access and means that users don’t have to write code for every single function—they can access built-in modules that help with issues in everyday programming and more.

Why using scripts with EspoCRM?

Some admin operations can be very easy to write in scripts while being complex to build in EspoCRM. And if those operations need to be executed only once, there is no added value in building a flowchart. Also, you might want to integrate EspoCRM with other systems, and again you might hit the limits of what you can do with flowcharts. In these and many more cases, just write a (Python) script.

Notable examples for which you should use a script:

• Migrate records from one EspoCRM instance to another
• Fix something in all records, once and never again
• Use fuzzy logic to find/match records, e.g. for deduplication

What can I do with scripts?

Let's dive into a few examples. Remember to download espo_api_client.py locally before running your scripts. The API client can be initialized with

from espo_api_client import EspoAPI
espo_client = EspoAPI(url='https://myespo.org', api_key='myapikey')

Warning

Ensure that the API key that you are using refers to an API user with the right permissions to perform the intended operations.

Get records

Get records of entity MyEntity in which myfield equals myvalue.

params = {
    "where": [
        {
            "type": "equals",
            "attribute": "myfield",
            "value": "myvalue"
        }
    ]
}
records = espo_client.request("GET", "MyEntity", params)["list"]

Tip

You can add as many conditions as you want in params, to filter the records

params = {
    "where": [
        {
            "type": "equals",
            "attribute": "myfield",
            "value": "myvalue"
        },
        {
            "type": "isNotNull",
            "attribute": "mysecondfield"
        },
        ...
    ]
}

Create records

Create a record of entity MyEntity.

payload = {
	'firstName': "Elvis",
	'lastName': "Presley",
	'gender': "male",
	'birthdate': "1935-01-08"
}
espo_client.request("POST", "MyEntity", payload)

Update records

Update field myfield of record with ID myID of entity MyEntity.

espo_client.request('PUT', "MyEntity/myID", {"myfield": "mynewvalue"})

Tip

You can update existing records in a bulk by combining GET and PUT

records = espo_client.request("GET", "MyEntity")["list"]
for record in records:
    espo_client.request('PUT', f"MyEntity/{record['id']}", {"myfield": "mynewvalue"})

Inspect API calls done by EspoCRM

• If you do any action within Espo, you can inspect the website and see which API calls are used to execute the action you just did.
• So, when being on the EspoCRM site, you can right click and choose “Inspect”, then go to “Network” and see the different actions that have taken place (eg. after creating a new field with conditionality).
• You can go through it and find the one you are interested in and inspect both the “Headers” and “Payload”.
• The information there could support you in writing your script.