# Search

Like '`/companies/`', a search can be performed on directorships by making a GET request to the '`/directorships/`' endpoint:

```
 https://api2.redflagalert.net/v4/directorships/
```

Returned resources will follow the JSON API format and will contain URLs in their '`links`' section to the company they are linked to.

To filter directorship search results, append the criteria as request parameters in any order.

#### Search Parameters

The following fields can currently be searched on:

| Field Name         | Notes                                                                 |
| ------------------ | --------------------------------------------------------------------- |
| `title`            | The directors title                                                   |
| `first_name`       | The directors first name                                              |
| `surname`          | The directors surname                                                 |
| `name`             | The combination of first\_name and surname, for example ‘Peter Smith’ |
| `town`             | The directors town of residence                                       |
| `county`           | The directors county of residence                                     |
| `nationality`      | The nationality of the director                                       |
| `postcode`         | The postcode of the directors residence                               |
| `occupation`       | The occupation of the director                                        |
| `appointment_type` | The type of the appointment                                           |

The searches can be combined. For example, to find directorships held by British nationals with the surname Morgan, the query would be:

```
https://api2.redflagalert.net/v4/directorships/?nationality=British&surname=Morgan
```

When performing name searches, the '`name`' field searches on full names. For example, the following query will only return directorships held by people called Peter Smith:

```
https://api2.redflagalert.net/v4/directorships/?first_name=Peter&surname=Smith
```

While the following search will return all directorships held by people whose name is either similar to 'Peter' or 'Smith', with the most relevant results returned first:

```
https://api2.redflagalert.net/v4/directorships/?name=Peter%20Smith
```

This means that 'Peter Smith' will rank highest, then 'Peter Smith Jones' then lastly, entries like 'James Smith’.

If an unrecognised field name is included in search parameters, it will be ignored.

To also receive the companies the directorships are linked to, append the 'company' string in the 'include=' GET parameter:

```
https://api2.redflagalert.net/v4/directorships/?include=company
```

The response will be a compound document (see <http://jsonapi.org/format/#document-compound-> documents for format) containing the original search results along with the companies. All results are paginated.

```
https://api2.redflagalert.net/v4/directorships/?include=company
```


---

# 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://developer.redflagalert.net/directors/search.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.