> For the complete documentation index, see [llms.txt](https://docs.ipaper.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipaper.io/flipbook-backend-api/search/search-papers-by-custom-fields.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.