# SearchPapersByCustomFields

## Description

Searches flipbooks by custom field values.

## Parameters

| Name       | Value                                                                            |
| ---------- | -------------------------------------------------------------------------------- |
| categoryID | The category whose descendants should be searched                                |
| xmlOptions | The xmlOptions parameter is used for specifying the search options in XML format |

### xmlOptions

* There must be at least one criteria.
* Criteria field values are automatically returned in the customfields section for result papers.
* Any custom fields that should be returned, and are not part of a criteria, should be added to the includedcustomfields section of the options.
* Each custom field criteria will have its value validated according to the field datatype.

#### **Sample Options**

<table><thead><tr><th>Element</th><th width="133">Required</th><th>Value</th></tr></thead><tbody><tr><td>customfieldcriterias</td><td>Yes</td><td>The usewildcards attribute is optional, default is false. Must only be specified for string type custom fields. Wildcard searches can be performed, using % as wildcard character</td></tr><tr><td>includedcustomfields</td><td>No</td><td>The include all attribute is optional, default is false. Returns all custom field values for the Flipbook. Use with care as amount of data may increase if many fields are defined</td></tr></tbody></table>

```xml
<options>
    <customfieldcriterias>
        <field name="[CriteriaFieldName]" usewildcards="[true/false]" value="[Value]" />
        ...
    </customfieldcriterias>
    <includedcustomfields includeall="[true/false]">
        <field name="[IncludedFieldName]"/>
        ...
    </includedcustomfields>
</options>
```

## Sample Response

{% hint style="info" %}
**Note:**

The lastprocessed field is only included if the Flipbook has been processed. Date is in 24H format.
{% endhint %}

{% hint style="info" %}
**Note:**

The pdffilesize field is only included if the Flipbook has been processed. File size is specified in KB.
{% endhint %}

```xml
<?xml version="1.0" encoding="utf-8"?>
<result>
  <code><![CDATA[SUCCESS]]></code>
  <message><![CDATA[Search results returned.]]></message>
  <data>
    <papers>
      <paper id="1120" name="Dot_Matrix_Range" url="/demos/DotMatrixRange/" lastprocessed="2009-03-15 15:27:00" pdffilesize="1357">
        <customfields>
          <field name="TestField" type="int" null="True"><![CDATA[]]></field>
          <field name="date" type="datetime" null="False"><![CDATA[2009-07-25]]></field>
        </customfields>
      </paper>
      ...
    </papers>
  </data>
</result>
```

## Return Codes

* SUCCESS
* ERROR
* SEARCH\_CUSTOMFIELD\_DATATYPE\_DOES\_NOT\_SUPPORT\_WILDCARDS
* SEARCH\_NO\_CUSTOM\_FIELD\_CRITERIAS
* SEARCH\_TEMPORARILY\_UNAVAILABLE
* PAPER\_DOES\_NOT\_EXIST
* PAPER\_MUST\_BE\_CATEGORY
* PAPER\_MUST\_NOT\_BE\_CATEGORY


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ipaper.io/flipbook-backend-api/search/search-papers-by-custom-fields.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.