API Entry

Compatibility

EE2, EE3, EE4, EE5, EE6, EE7

Installation

The Entry API comes natively with the Webservice module.

Methods

POST `/index.php/webservice/entry` — Create Entry

Create a new entry in a channel.

Request Parameters

Parameter	Type	Required	Description
`channel_name`	`string`	Required	The name of the channel where the entry must be inserted
`title`	`string`	Required	The title for the entry
`status`	`string`	Optional	The status of the entry
`allow_comments`	`boolean`	Optional	Allow comments?
`sticky`	`boolean`	Optional	Is the entry sticky?
`custom_fields`	`mixed`	Optional	Any custom fields can be added
`category`	`array`	Optional	Array of category IDs
`member_id`	`integer`	Optional	Member ID, otherwise defaults to the logged-in user

Headers

Header	Value
`Content-Type`	`application/json`

Request Example

php

$client = new \GuzzleHttp\Client();

$request = new \GuzzleHttp\Psr7\Request(
    'POST',
    'https://your-domain.com/index.php/webservice/entry',
    ['Content-Type' => 'application/json'],
    json_encode([
        'auth' => [
            'session_id' => 'fa78db6b673b83c211e8cc7153528e9087f62de0',
        ],
        'data' => [
            'channel_name'   => 'news_channel',
            'title'          => 'Test entry',
            'status'         => 'Closed',
            'sticky'         => 'y',
            'allow_comments' => 'n',
            'news_body'      => 'This is a full body text',
            'news_extended'  => 'This is some small text',
            'category'       => [1, 2, 3, 4],
            'custom_file_field' => [
                'filedata' => base64_encode(file_get_contents('path_to_image.jpg')),
                'filename' => 'filename.jpg',
                'dir_id'   => 6,
            ],
        ],
    ])
);

$response = $client->send($request, ['timeout' => 2]);

Response — `200 OK`

json

{
    "success": true,
    "message": "entry created",
    "data": [
        {
            "entry_id": 42
        }
    ]
}

Response Fields

Field	Type	Description
`success`	`boolean`	`true` when the entry was created successfully
`message`	`string`	Human readable status message
`data[].entry_id`	`integer`	The ID of the newly created entry

GET `/index.php/webservice/entry` — Search / Read Entry

Search or retrieve entries from a channel. Since v3.5, read_entry and search_entry are the same method.

Note: the order of the request parameters will be the order of the query.

Request Parameters

Parameter	Type	Required	Description
`entry_id`	`integer`	Optional	Fetch a single entry by ID
`channel`	`string`	Optional	Channel name — returns all entries in this channel
`channel_id`	`integer`	Optional	Search by Channel ID
`url_title`	`string`	Optional	Search by URL title
`status`	`string`	Optional	Filter by entry status
`limit`	`integer`	Optional	Maximum number of results (used with `offset`)
`offset`	`integer`	Optional	Result offset (used with `limit`)
`orderby`	`string`	Optional	Sort results by this field
`sort`	`string`	Optional	Sort direction (`asc` or `desc`)
`start_on`	`string`	Optional	Filter entries from this date
`stop_before`	`string`	Optional	Filter entries before this date
`output_fields`	`array`	Optional	Specify fields to return (also applies to relationships)
`search_all`	`string`	Optional	Search across all custom fields
`grid_field` / `matrix_field`	`string`	Optional	Search in any grid/matrix field
`grid_field[col_name]` / `matrix_field[cell_name]`	`string`	Optional	Search in a specific grid/matrix cell
`cat:[field_name]`	`string`	Optional	Search on category fields (`cat_id`, `group_id`, `cat_name`, `cat_url_title`, or a custom field)
`include`	`string`	Optional	Include extra data: `channel\|categories\|author`
`return`	`string`	Optional	Return only stats: `data[return]=meta`

Headers

Header	Value
`Content-Type`	`application/json`

Request Example

GET /index.php/webservice/entry?auth[session_id]=fa78db6b673b83c211e8cc7153528e9087f62de0&data[site_id]=1&data[entry_id]=43

php

$client = new \GuzzleHttp\Client();

$response = $client->get('https://your-domain.com/index.php/webservice/entry', [
    'query' => [
        'auth' => [
            'session_id' => 'fa78db6b673b83c211e8cc7153528e9087f62de0',
        ],
        'data' => [
            'site_id'  => 1,
            'entry_id' => 43,
        ],
    ],
    'timeout' => 2,
]);

Response — `200 OK`

json

{
    "success": true,
    "message": "entries found",
    "data": [
        {
            "entry_id": 43,
            "title": "My Entry",
            "status": "open",
            "channel_name": "news_channel"
        }
    ]
}

Response Fields

Field	Type	Description
`success`	`boolean`	`true` when the request succeeded
`message`	`string`	Human readable status message
`data[]`	`array`	Array of matching entry objects
`data[].entry_id`	`integer`	The entry ID
`data[].title`	`string`	The entry title
`data[].status`	`string`	The entry status

Search Mechanism

Basic Operators

Type	Operator	Example
Contains	(empty)	`data[body]=test`
Contains with wildcard	(empty)	`data[body]=~test` → results in `%test%`
Contains NOT	(empty)	`data[body]=not test`
Exact matching	`=`	`data[body]==test`
Numeric matching	`<` `>` `<=` `>=`	`data[body]=>10`
Empty field	`IS_EMPTY`	`data[body]=IS_EMPTY`
Not empty field	`IS_EMPTY`	`data[body]=not IS_EMPTY`

OR / AND

By default the query is built with AND. To switch to OR, add or before the value:

data[title]=or john

Multiple Values

Use a pipe | or comma , to match multiple values (results in an OR query):

data[title]=test|john

sql

title = 'test' OR title = 'john'

Groups

Group conditions like you would in SQL: (field = '4' OR field = '5') AND (field = '2' OR field = '3')

The group name can be anything, but must be unique per group.

data[group_one][group_and][][title]=test|john&data[group_two][group_and][][title]=willem|doe

sql

(title = 'test' OR title = 'john') AND (title = 'willem' OR title = 'doe')

PUT `/index.php/webservice/entry` — Update Entry

Update an existing entry by entry ID or search parameters.

Request Parameters

Parameter	Type	Required	Description
`entry_id`	`integer`	Required*	The entry ID to update
`search[]`	`array`	Required*	Identify the entry via search (see Search Mechanism)
`title`	`string`	Optional	The title for the entry
`status`	`string`	Optional	The status of the entry
`allow_comments`	`boolean`	Optional	Allow comments?
`sticky`	`boolean`	Optional	Is the entry sticky?
`custom_fields`	`mixed`	Optional	Any custom field(s)
`category`	`array`	Optional	Array of category IDs
`member_id`	`integer`	Optional	Member ID, otherwise defaults to the logged-in user

*Either entry_id or search[] is required.

Headers

Header	Value
`Content-Type`	`application/json`

Request Example — by Entry ID

PUT /index.php/webservice/entry?auth[session_id]=fa78db6b673b83c211e8cc7153528e9087f62de0&data[site_id]=1&data[entry_id]=3988&data[title]=updated&data[status]=open

php

$client = new \GuzzleHttp\Client();

$request = new \GuzzleHttp\Psr7\Request(
    'PUT',
    'https://your-domain.com/index.php/webservice/entry',
    ['Content-Type' => 'application/json'],
    json_encode([
        'auth' => [
            'session_id' => 'fa78db6b673b83c211e8cc7153528e9087f62de0',
        ],
        'data' => [
            'site_id'        => 1,
            'entry_id'       => 3988,
            'title'          => 'Updated title',
            'status'         => 'open',
            'sticky'         => 'y',
            'allow_comments' => 'n',
            'news_body'      => 'This is a full body text',
            'news_extended'  => 'This is some small text',
        ],
    ])
);

$response = $client->send($request, ['timeout' => 2]);

💻 Request Example — by Search

⚠️ The webservice returns an error if multiple entries match. Use force to update the first match. Updating by entry_id is safer but requires an extra request to look up the ID first.

php

$request = new \GuzzleHttp\Psr7\Request(
    'PUT',
    'https://your-domain.com/index.php/webservice/entry',
    ['Content-Type' => 'application/json'],
    json_encode([
        'auth' => [
            'session_id' => 'fa78db6b673b83c211e8cc7153528e9087f62de0',
        ],
        'data' => [
            'search' => [
                'custom_field' => '=test', // = sign is for explicit matching
                'force'        => true,    // update first match if multiple found
            ],
            'title'  => 'Updated title',
            'status' => 'Closed',
        ],
    ])
);

Response — `200 OK`

json

{
    "success": true,
    "message": "entry updated",
    "data": [
        {
            "entry_id": 3988
        }
    ]
}

📤 Response Fields

Field	Type	Description
`success`	`boolean`	`true` when the entry was updated successfully
`message`	`string`	Human readable status message
`data[].entry_id`	`integer`	The ID of the updated entry

DELETE `/index.php/webservice/entry` — Delete Entry

Delete an entry by its entry ID.

Request Parameters

Parameter	Type	Required	Description
`entry_id`	`integer`	Required	The entry ID to delete

Headers

Header	Value
`Content-Type`	`application/json`

Request Example

DELETE /index.php/webservice/entry?auth[username]=person@gmail.com&auth[password]=1232&data[site_id]=1&data[entry_id]=3983

php

$client = new \GuzzleHttp\Client();

$request = new \GuzzleHttp\Psr7\Request(
    'DELETE',
    'https://your-domain.com/index.php/webservice/entry',
    ['Content-Type' => 'application/json'],
    json_encode([
        'auth' => [
            'username' => 'person@gmail.com',
            'password' => '1232',
        ],
        'data' => [
            'site_id'  => 1,
            'entry_id' => 3983,
        ],
    ])
);

$response = $client->send($request, ['timeout' => 2]);

Response — `200 OK`

json

{
    "success": true,
    "message": "entry deleted",
    "data": []
}

Response Fields

Field	Type	Description
`success`	`boolean`	`true` when the entry was deleted successfully
`message`	`string`	Human readable status message

Hooks

webservice_create_entry_start

(added in v3.2.1)

$entry_data = ee()->extensions->call('webservice_create_entry_start', $entry_data);

webservice_create_entry_end

(added in v2.2)

ee()->extensions->call('webservice_create_entry_end', $entry_id, $post_data);

webservice_read_entry_start

(added in v3.2.1)

$entry_data = ee()->extensions->call('webservice_read_entry_start', $entry_data);

webservice_read_entry

(added in v4.4.2)
Runs after the validation

$entry_data = ee()->extensions->call('webservice_read_entry', $entry_data, $post_data);

webservice_read_entry_end

(added in v2.2)

$entry_data = ee()->extensions->call('webservice_read_entry_end', $entry_data);

webservice_update_entry_start

(added in v3.2.1)

$entry_data = ee()->extensions->call('webservice_update_entry_start', $entry_data);

webservice_update_entry

(added in v4.4.2)
Runs after the validation

$entry_data = ee()->extensions->call('webservice_update_entry', $entry_data, $post_data);

webservice_update_entry_end

(added in v2.2)

ee()->extensions->call('webservice_update_entry_end', $entry_data, $post_data);

webservice_delete_entry_start

(added in v3.2.1)

$entry_data = ee()->extensions->call('webservice_delete_entry_start', $entry_data);

webservice_delete_entry_end

(added in v2.2)

ee()->extensions->call('webservice_delete_entry_end', '');

webservice_modify_search

(added in v4.0)
With this hook you can extend the search by your own. Just make sure the hook will return an array of entry_ids.

$entry_ids = ee()->extensions->call('webservice_search_entry_per_entry', $values, $fields);

webservice_search_entry_per_entry

(added in v3.2)

$entry_data = ee()->extensions->call('webservice_search_entry_per_entry', $entry_data);

webservice_search_entry_per_entry

(added in v3.2)

$entry_data = ee()->extensions->call('webservice_search_entry_per_entry', $entry_data);

webservice_search_entry_start

(added in v3.2.1)

$entry_data = ee()->extensions->call('webservice_search_entry_start', $entry_data);

webservice_search_entry_end

(added in v2.2)

$entry_data = ee()->extensions->call('webservice_search_entry_end', $entry_data);

webservice_entry_row

(added in v3.5)
WIll be called when reading an entry

$entry_data = ee()->extensions->call('webservice_entry_row', $entry_data);

webservice_read_entry_matrix

(added in v4.0)

ee()->extensions->call('webservice_read_entry_matrix', $value, $col_settings);

webservice_read_entry_grid

(added in v4.0)

ee()->extensions->call('webservice_read_entry_grid', $value, $col_settings);

API Entry ​

Compatibility ​

Installation ​

Methods ​

POST /index.php/webservice/entry — Create Entry ​

Request Parameters ​

Headers ​

Request Example ​

Response — 200 OK ​

Response Fields ​

GET /index.php/webservice/entry — Search / Read Entry ​

Request Parameters ​

Headers ​

Request Example ​

Response — 200 OK ​

Response Fields ​

Search Mechanism ​

Basic Operators ​

OR / AND ​

Multiple Values ​

Groups ​

PUT /index.php/webservice/entry — Update Entry ​

Request Parameters ​

Headers ​

Request Example — by Entry ID ​

💻 Request Example — by Search ​

Response — 200 OK ​

📤 Response Fields ​

DELETE /index.php/webservice/entry — Delete Entry ​

Request Parameters ​

Headers ​

Request Example ​

Response — 200 OK ​

Response Fields ​

Hooks ​

webservice_create_entry_start ​

webservice_create_entry_end ​

webservice_read_entry_start ​

webservice_read_entry ​

webservice_read_entry_end ​

webservice_update_entry_start ​

webservice_update_entry ​

webservice_update_entry_end ​

webservice_delete_entry_start ​

webservice_delete_entry_end ​

webservice_modify_search ​

webservice_search_entry_per_entry ​

webservice_search_entry_per_entry ​

webservice_search_entry_start ​

webservice_search_entry_end ​

webservice_entry_row ​

webservice_read_entry_matrix ​

webservice_read_entry_grid ​

API Entry

Compatibility

Installation

Methods

POST `/index.php/webservice/entry` — Create Entry

Request Parameters

Headers

Request Example

Response — `200 OK`

Response Fields

GET `/index.php/webservice/entry` — Search / Read Entry

Request Parameters

Headers

Request Example

Response — `200 OK`

Response Fields

Search Mechanism

Basic Operators

OR / AND

Multiple Values

Groups

PUT `/index.php/webservice/entry` — Update Entry

Request Parameters

Headers

Request Example — by Entry ID

💻 Request Example — by Search

Response — `200 OK`

📤 Response Fields

DELETE `/index.php/webservice/entry` — Delete Entry

Request Parameters

Headers

Request Example

Response — `200 OK`

Response Fields

Hooks

webservice_create_entry_start

webservice_create_entry_end

webservice_read_entry_start

webservice_read_entry

webservice_read_entry_end

webservice_update_entry_start

webservice_update_entry

webservice_update_entry_end

webservice_delete_entry_start

webservice_delete_entry_end

webservice_modify_search

webservice_search_entry_per_entry

webservice_search_entry_per_entry

webservice_search_entry_start

webservice_search_entry_end

webservice_entry_row

webservice_read_entry_matrix

webservice_read_entry_grid