> For the complete documentation index, see [llms.txt](https://docs.filemail.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.filemail.com/handling-contacts.md).

# Handling contacts

As per now, the only available operation on contacts through our Public API is searching the contact list. Any matches is returned in an array with stored Name and E-mail and also a parameter `isGroup` that if `true` means that this is a group of contacts.

## POST /contact/search

> Performs a search in current user's contacts and contact groups. Returns a list of matching contacts and groups.

```json
{"openapi":"3.0.4","info":{"title":"Filemail REST API","version":"2.0"},"tags":[{"name":"Contact"}],"servers":[{"url":"https://api-public.filemail.com","description":"Production"}],"paths":{"/contact/search":{"post":{"tags":["Contact"],"description":"Performs a search in current user's contacts and contact groups. Returns a list of matching contacts and groups.","requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/ContactSearchRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/ContactSearchRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/ContactSearchRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/ContactSearchRequest"}}}},"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ContactSearchResultBaseResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/ContactSearchResultBaseResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/ContactSearchResultBaseResponse"}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"application/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/FilemailErrorResponse"}}}}}}}},"components":{"schemas":{"ContactSearchRequest":{"required":["term"],"type":"object","properties":{"term":{"minLength":1,"type":"string","description":"The search phrase. For contact groups - it matches any substring of the group name. For contacts - it matches any substring of contact name or email address."},"exclude":{"type":"array","items":{"type":"string"},"description":"List of email addresses and contact group names to exclude from search results.","nullable":true},"limit":{"type":"integer","description":"Optional limit of returned search results. Note that results are first sorted by contact/group name, then by email. Search results will be limited to the requested limit based on the mentioned sort order.","format":"int32","nullable":true}},"additionalProperties":false},"ContactSearchResultBaseResponse":{"type":"object","properties":{"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"$ref":"#/components/schemas/ContactSearchResult"},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"FilemailStatusEnum":{"enum":["OK","UnknownError","InvalidParameter","InputParameterMissing","InvalidEmail","NotFound","CantRemoveLastCorpAdmin","CantRemoveYourself","CantRemoveAdminRoleForYourself","ServiceInterruption","ImageThumbTooExpensive","MissingApikey","InvalidApikey","ApiKeyQuotaExceeded","RateLimitExceeded","WrongUsernamePassword","PasswordTooWeak","InvalidOrExpiredLoginToken","AccountExpired","CaptchaRequiredForNextLogin","LDAPUnableToCreateUser","LDAPWrongUsernamePassword","AccessDenied","CorpAuthenticationRequired","InvalidRequest","UseSsoLink","SsoSessionExpired","SsoCompanyDoesNotUseAdLogin","SsoGroupIdNotSupported","SsoSignatureInvalid","TwoFactorTokenNotFound","TwoFactorUserNotFound","TwoFactorPinNotValid","PasswordResetRequired","SsoUserDisabled","SsoLoginGeneralError","SsoMissingAuthCode","RefreshTokenExpired","RefreshTokenAlreadyUsed","SsoResetPasswordBlocked","AuthorizationFailure","CorpAuthorizationFailed","BusinessAccountExistsRegistrationRequired","UserAccountExistsLoginRequired","Blocked","AllFileserversBusy","FreeLimitReached","AccountExpiredAndOutOfTransferCredits","EmailNotVerified","FeatureAvailableForRegisteredUsers","FileSizeBlockSender","FileSizeBlockRecipient","TooManyRecipients","InvalidTransferState","TransferExpired","PasswordRequired","UploadNotComplete","FileIsDeleted","UploadRecentlyUpdated","FileIsInfected","SubscriptionNotFound","EmailAlreadyRegistered","SignupFormNotAccepted","SessionPasswordNotFound","SessionCustRefNotFound","AllUserLicencesesInUse","RegistrationRequired","PaymentMethodNotAccepted","SubscriptionCancellationFailed","InvalidSubscriptionState","PaymentFailed","ReceiptVerificationError","ReceiptAlreadyUsedForActivation","SubscriptionNotPaid","SubscriptionAlreadyActivated","SubscriptionPurchaseAckFailed","InvoiceFailure","InvalidDowngrade","InvalidDataState","InvalidMembership","ContactsLimitReached","StorageCapReached","ContactsFileParseError","RecoveryNotPossible","ImageFileError","ContactDuplicate","ChunkDownloadError","FileOperationError","IncomingPageBlockedInOverdue","NotAVideo","OperationCancelled","VideoFileError","FileRequestRecipientLimitTrial","FileRequestRecipientLimitBasic","FileRequestShareLimitTrial","FileRequestShareLimitBasic","FileRequestBlock","FileRequestShareLimitTimeframe"],"type":"string"},"ContactSearchResult":{"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ContactSearchItem"},"description":"A list of matching contacts and contact groups."}},"additionalProperties":false},"ContactSearchItem":{"type":"object","properties":{"name":{"type":"string","description":"The contact or contact group name."},"email":{"type":"string","description":"The contact email. This property is not returned for contact groups."},"isGroup":{"type":"boolean","description":"`True` when the object represents a contact group. `False` when it represents a contact."},"memberCount":{"type":"integer","description":"Number of contacts within a contact group. This field is not returned for contacts.","format":"int32","nullable":true}},"additionalProperties":false,"description":"Represents single contat or contact group in the contact search results."},"FilemailErrorResponse":{"type":"object","properties":{"validationerrors":{"type":"array","items":{"$ref":"#/components/schemas/ValidationError"},"description":"List of validation errors when the request was not properly formed.","nullable":true},"responsestatus":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorid":{"type":"string","nullable":true},"errormessage":{"type":"string","nullable":true},"data":{"description":"This field contains endpoint-sepcific response data.","nullable":true},"errorcode":{"type":"integer","description":"Numeric representation of the `responsestatus` field.","format":"int32","nullable":true,"readOnly":true}},"additionalProperties":false},"ValidationError":{"required":["propertyName"],"type":"object","properties":{"propertyName":{"minLength":1,"type":"string","description":"Name of the invalid property contained in the request body or query string."},"errorCode":{"$ref":"#/components/schemas/FilemailStatusEnum"},"errorMessage":{"type":"string","description":"Message explaining the validation error.","nullable":true}},"additionalProperties":false}}}}
```


---

# 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.filemail.com/handling-contacts.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.