### Ploomes API OData Query Examples

Source: https://developers.ploomes.com/index

Examples demonstrating the usage of OData query parameters for filtering, selecting, sorting, and expanding data from the Ploomes API. These parameters help control the data returned by API requests.

```url
https://api2.ploomes.com/Deals?$top=10
```

```url
https://api2.ploomes.com/Deals?$top=10 &$skip=20
```

```url
https://api2.ploomes.com/Deals?$select=Title
```

```url
https://api2.plomes.com/Deals?$expand=OtherProperties
```

```url
https://api2.ploomes.com/Deals?$orderby=Amount+asc
```

```url
https://api2.ploomes.com/Deals?$filter=Id+eq+13123
```

--------------------------------

### Authentication - Get User-Key

Source: https://developers.ploomes.com/index

To use the API, you first need to obtain your User-Key. This key is used in the header of all requests. Only administrators can create or delete integration keys. Follow the steps in the Ploomes administration section to generate a User-Key.

```APIDOC
## Authentication - Get User-Key

### Description
To use the API, you first need to obtain your User-Key. This key is used in the header of all requests. Only administrators can create or delete integration keys. Follow the steps in the Ploomes administration section to generate a User-Key.

1. Go to Ploomes and navigate to the Administration tab.
2. In the Integrations section, click the "Integration Users" button.
3. Click "New user", fill in the user's name, email, and access profile, and confirm creation.
4. Select the created user and copy their User-Key from the "API Key" field.
```

--------------------------------

### Ploomes API Custom Field Filtering

Source: https://developers.ploomes.com/index

Example of filtering API results based on the values of custom fields. This query demonstrates using the 'FieldId' for performance and applying conditions on custom field values, such as string equality.

```url
https://api2.ploomes.com/Deals?filter=((((OtherProperties/any(o:+o/FieldId+eq+245552+and+(o/StringValue+eq+'teste'))))))
```

--------------------------------

### Products API

Source: https://developers.ploomes.com/index

Endpoints for managing products, including their families, groups, and parts.

```APIDOC
## GET /api/Products

### Description
Retrieves a list of products.

### Method
GET

### Endpoint
/api/Products
```

```APIDOC
## POST /api/Products

### Description
Creates a new product.

### Method
POST

### Endpoint
/api/Products
```

```APIDOC
## PATCH /api/Products({Id})

### Description
Updates an existing product.

### Method
PATCH

### Endpoint
/api/Products({Id})
```

```APIDOC
## DELETE /api/Products({Id})

### Description
Deletes a product.

### Method
DELETE

### Endpoint
/api/Products({Id})
```

```APIDOC
## GET /api/Products@Families

### Description
Retrieves product families.

### Method
GET

### Endpoint
/api/Products@Families
```

```APIDOC
## POST /api/Products@Families

### Description
Creates a new product family.

### Method
POST

### Endpoint
/api/Products@Families
```

```APIDOC
## PATCH /api/Products@Families({Id})

### Description
Updates an existing product family.

### Method
PATCH

### Endpoint
/api/Products@Families({Id})
```

```APIDOC
## DELETE /api/Products@Families({Id})

### Description
Deletes a product family.

### Method
DELETE

### Endpoint
/api/Products@Families({Id})
```

```APIDOC
## GET /api/Products@Groups

### Description
Retrieves product groups.

### Method
GET

### Endpoint
/api/Products@Groups
```

```APIDOC
## POST /api/Products@Groups

### Description
Creates a new product group.

### Method
POST

### Endpoint
/api/Products@Groups
```

```APIDOC
## PATCH /api/Products@Groups({Id})

### Description
Updates an existing product group.

### Method
PATCH

### Endpoint
/api/Products@Groups({Id})
```

```APIDOC
## DELETE /api/Products@Groups({Id})

### Description
Deletes a product group.

### Method
DELETE

### Endpoint
/api/Products@Groups({Id})
```

```APIDOC
## GET /api/Products@Parts

### Description
Retrieves product parts.

### Method
GET

### Endpoint
/api/Products@Parts
```

```APIDOC
## POST /api/Products@Parts

### Description
Creates a new product part.

### Method
POST

### Endpoint
/api/Products@Parts
```

```APIDOC
## PATCH /api/Products@Parts({Id})

### Description
Updates an existing product part.

### Method
PATCH

### Endpoint
/api/Products@Parts({Id})
```

```APIDOC
## DELETE /api/Products@Parts({Id})

### Description
Deletes a product part.

### Method
DELETE

### Endpoint
/api/Products@Parts({Id})
```

--------------------------------

### Deals API

Source: https://developers.ploomes.com/index

Endpoints for managing deals, including stages, status, loss reasons, pipelines, and actions like winning, losing, or reopening deals.

```APIDOC
## GET /api/Deals

### Description
Retrieves a list of deals.

### Method
GET

### Endpoint
/api/Deals
```

```APIDOC
## POST /api/Deals

### Description
Creates a new deal.

### Method
POST

### Endpoint
/api/Deals
```

```APIDOC
## PATCH /api/Deals({Id})

### Description
Updates an existing deal.

### Method
PATCH

### Endpoint
/api/Deals({Id})
```

```APIDOC
## DELETE /api/Deals({Id})

### Description
Deletes a deal.

### Method
DELETE

### Endpoint
/api/Deals({Id})
```

```APIDOC
## POST /api/Deals({Id})/Win

### Description
Marks a deal as won.

### Method
POST

### Endpoint
/api/Deals({Id})/Win
```

```APIDOC
## POST /api/Deals({Id})/Lose

### Description
Marks a deal as lost.

### Method
POST

### Endpoint
/api/Deals({Id})/Lose
```

```APIDOC
## POST /api/Deals({Id})/Reopen

### Description
Reopens a closed deal.

### Method
POST

### Endpoint
/api/Deals({Id})/Reopen
```

```APIDOC
## GET /api/Deals@Stages

### Description
Retrieves deal stages.

### Method
GET

### Endpoint
/api/Deals@Stages
```

```APIDOC
## GET /api/Deals@Status

### Description
Retrieves deal status options.

### Method
GET

### Endpoint
/api/Deals@Status
```

```APIDOC
## GET /api/Deals@LossReasons

### Description
Retrieves reasons for lost deals.

### Method
GET

### Endpoint
/api/Deals@LossReasons
```

```APIDOC
## GET /api/Deals@Pipelines

### Description
Retrieves deal pipelines.

### Method
GET

### Endpoint
/api/Deals@Pipelines
```

```APIDOC
## POST /api/Deals@Pipelines

### Description
Creates a new deal pipeline.

### Method
POST

### Endpoint
/api/Deals@Pipelines
```

```APIDOC
## PATCH /api/Deals@Pipelines({Id})

### Description
Updates an existing deal pipeline.

### Method
PATCH

### Endpoint
/api/Deals@Pipelines({Id})
```

```APIDOC
## DELETE /api/Deals@Pipelines({Id})

### Description
Deletes a deal pipeline.

### Method
DELETE

### Endpoint
/api/Deals@Pipelines({Id})
```

--------------------------------

### Ploomes API Limits and Best Practices

Source: https://developers.ploomes.com/index

Information on API request limits, entity limits, payload size, and recommended practices for efficient API usage.

```APIDOC
## API Limits

*   **Request Limit**: 120 requests per minute per account (aggregated across all integrations).
*   **Entity Limits**: Some entities are limited to 300 items per GET request: Contacts, Deals, Cities, Tasks, Orders, and Quotes.
*   **Payload Limit**: Maximum accepted payload size is 10MB.

## Best Practices

*   **Pagination**: Use `$top` and `$skip` for pagination, ideally limiting pages to 100 items.
*   **Field Selection**: Use `$select` to retrieve only essential data, reducing payload size and improving performance.
*   **Concurrency**: Assume your application competes for rate limits and resources. Implement conservative usage limits.
*   **Asynchronous Requests**: Utilize asynchronous requests when possible to better manage limits and errors.
*   **Avoid Simultaneous Calls**: Do not make simultaneous API calls unless your use case specifically benefits from it.
```

--------------------------------

### Accounts API

Source: https://developers.ploomes.com/index

Endpoints for managing account information.

```APIDOC
## GET /api/Account

### Description
Retrieves a list of accounts.

### Method
GET

### Endpoint
/api/Account
```

```APIDOC
## PATCH /api/Account({Id})

### Description
Updates an existing account.

### Method
PATCH

### Endpoint
/api/Account({Id})
```

--------------------------------

### Orders API

Source: https://developers.ploomes.com/index

Endpoints for managing orders, including stages and status.

```APIDOC
## GET /api/Orders

### Description
Retrieves a list of orders.

### Method
GET

### Endpoint
/api/Orders
```

```APIDOC
## POST /api/Orders

### Description
Creates a new order.

### Method
POST

### Endpoint
/api/Orders
```

```APIDOC
## PATCH /api/Orders({Id})

### Description
Updates an existing order.

### Method
PATCH

### Endpoint
/api/Orders({Id})
```

```APIDOC
## DELETE /api/Orders({Id})

### Description
Deletes an order.

### Method
DELETE

### Endpoint
/api/Orders({Id})
```

```APIDOC
## GET /api/Orders@Stages

### Description
Retrieves order stages.

### Method
GET

### Endpoint
/api/Orders@Stages
```

```APIDOC
## POST /api/Orders@Stages

### Description
Creates a new order stage.

### Method
POST

### Endpoint
/api/Orders@Stages
```

```APIDOC
## PATCH /api/Orders@Stages({Id})

### Description
Updates an existing order stage.

### Method
PATCH

### Endpoint
/api/Orders@Stages({Id})
```

```APIDOC
## DELETE /api/Orders@Stages({Id})

### Description
Deletes an order stage.

### Method
DELETE

### Endpoint
/api/Orders@Stages({Id})
```

--------------------------------

### Departments API

Source: https://developers.ploomes.com/index

Endpoints for managing departments.

```APIDOC
## GET /api/Departments

### Description
Retrieves a list of departments.

### Method
GET

### Endpoint
/api/Departments
```

```APIDOC
## POST /api/Departments

### Description
Creates a new department.

### Method
POST

### Endpoint
/api/Departments
```

```APIDOC
## PATCH /api/Departments({Id})

### Description
Updates an existing department.

### Method
PATCH

### Endpoint
/api/Departments({Id})
```

```APIDOC
## DELETE /api/Departments({Id})

### Description
Deletes a department.

### Method
DELETE

### Endpoint
/api/Departments({Id})
```

--------------------------------

### InteractionRecords API

Source: https://developers.ploomes.com/index

Endpoints for managing interaction records.

```APIDOC
## GET /api/InteractionRecords

### Description
Retrieves a list of interaction records.

### Method
GET

### Endpoint
/api/InteractionRecords
```

```APIDOC
## POST /api/InteractionRecords

### Description
Creates a new interaction record.

### Method
POST

### Endpoint
/api/InteractionRecords
```

```APIDOC
## PATCH /api/InteractionRecords({Id})

### Description
Updates an existing interaction record.

### Method
PATCH

### Endpoint
/api/InteractionRecords({Id})
```

```APIDOC
## DELETE /api/InteractionRecords({Id})

### Description
Deletes an interaction record.

### Method
DELETE

### Endpoint
/api/InteractionRecords({Id})
```

--------------------------------

### Currencies API

Source: https://developers.ploomes.com/index

Endpoint for retrieving currency information.

```APIDOC
## GET /api/Currencies

### Description
Retrieves a list of currencies.

### Method
GET

### Endpoint
/api/Currencies
```

--------------------------------

### Documents API

Source: https://developers.ploomes.com/index

Endpoints for managing documents.

```APIDOC
## GET /api/Documents

### Description
Retrieves a list of documents.

### Method
GET

### Endpoint
/api/Documents
```

```APIDOC
## POST /api/Documents

### Description
Uploads a new document.

### Method
POST

### Endpoint
/api/Documents
```

```APIDOC
## PATCH /api/Documents({Id})

### Description
Updates an existing document.

### Method
PATCH

### Endpoint
/api/Documents({Id})
```

```APIDOC
## DELETE /api/Documents({Id})

### Description
Deletes a document.

### Method
DELETE

### Endpoint
/api/Documents({Id})
```

--------------------------------

### Fields API

Source: https://developers.ploomes.com/index

Endpoints for managing custom fields, including their options and types.

```APIDOC
## GET /api/Fields

### Description
Retrieves a list of custom fields.

### Method
GET

### Endpoint
/api/Fields
```

```APIDOC
## POST /api/Fields

### Description
Creates a new custom field.

### Method
POST

### Endpoint
/api/Fields
```

```APIDOC
## PATCH /api/Fields({Key})

### Description
Updates an existing custom field.

### Method
PATCH

### Endpoint
/api/Fields({Key})
```

```APIDOC
## DELETE /api/Fields({Key})

### Description
Deletes a custom field.

### Method
DELETE

### Endpoint
/api/Fields({Key})
```

```APIDOC
## GET /api/Fields@Entities

### Description
Retrieves entities associated with custom fields.

### Method
GET

### Endpoint
/api/Fields@Entities
```

```APIDOC
## GET /api/Fields@OptionsTables

### Description
Retrieves options tables for custom fields.

### Method
GET

### Endpoint
/api/Fields@OptionsTables
```

```APIDOC
## POST /api/Fields@OptionsTables

### Description
Creates a new options table for a custom field.

### Method
POST

### Endpoint
/api/Fields@OptionsTables
```

```APIDOC
## GET /api/Fields@OptionsTables@Options

### Description
Retrieves options within an options table for custom fields.

### Method
GET

### Endpoint
/api/Fields@OptionsTables@Options
```

```APIDOC
## POST /api/Fields@OptionsTables@Options

### Description
Creates a new option within an options table for a custom field.

### Method
POST

### Endpoint
/api/Fields@OptionsTables@Options
```

```APIDOC
## PATCH /api/Fields@OptionsTables@Options({Id})

### Description
Updates an existing option within an options table for a custom field.

### Method
PATCH

### Endpoint
/api/Fields@OptionsTables@Options({Id})
```

```APIDOC
## DELETE /api/Fields@OptionsTables@Options({Id})

### Description
Deletes an option from an options table for a custom field.

### Method
DELETE

### Endpoint
/api/Fields@OptionsTables@Options({Id})
```

```APIDOC
## GET /api/Fields@Types

### Description
Retrieves types for custom fields.

### Method
GET

### Endpoint
/api/Fields@Types
```

--------------------------------

### OData Protocol

Source: https://developers.ploomes.com/index

This API utilizes the OData protocol for response manipulation. All requests can use the following query strings: _$top_, _$skip_, _$select_, _$expand_, _$orderby_, and _$filter_.

```APIDOC
## OData Protocol

### Description
This API utilizes the OData protocol for response manipulation. In all requests, the following query strings can be used: _$top_, _$skip_, _$select_, _$expand_, _$orderby_, and _$filter_.
```

--------------------------------

### DocumentTemplates API

Source: https://developers.ploomes.com/index

Endpoint for retrieving document template information.

```APIDOC
## GET /api/DocumentTemplates

### Description
Retrieves a list of document templates.

### Method
GET

### Endpoint
/api/DocumentTemplates
```

--------------------------------

### Operations API

Source: https://developers.ploomes.com/index

Endpoint for retrieving operation information.

```APIDOC
## GET /api/Operations

### Description
Retrieves a list of operations.

### Method
GET

### Endpoint
/api/Operations
```

--------------------------------

### Ploomes API OData Query Parameters

Source: https://developers.ploomes.com/index

This section details the standard OData query parameters available for the Ploomes API to filter, sort, and paginate data.

```APIDOC
## GET /deals

### Description
Retrieves a list of deals, supporting OData query parameters for filtering, sorting, and pagination.

### Method
GET

### Endpoint
/deals

### Parameters
#### Query Parameters
- **$top** (integer) - Optional - Limits the number of items returned in the response. Example: `?$top=10`
- **$skip** (integer) - Optional - Skips a specified number of items before returning results. Example: `?$top=10&$skip=20`
- **$select** (string) - Optional - Specifies which fields to return from the object. Example: `?$select=Title`
- **$expand** (string) - Optional - Expands related objects or properties. Example: `?$expand=OtherProperties`
- **$orderby** (string) - Optional - Orders the results based on a specific field. Example: `?$orderby=Amount+asc`
- **$filter** (string) - Optional - Filters the results based on a specific field and value. Example: `?$filter=Id+eq+13123`

### Request Example
```http
GET /deals?$top=10&$select=Title,Amount HTTP/1.1
Host: api2.ploomes.com
```

### Response
#### Success Response (200)
- **Deals** (array) - An array of deal objects.
  - **Title** (string) - The title of the deal.
  - **Amount** (number) - The value of the deal.
  - **OtherProperties** (array) - Custom fields associated with the deal.

#### Response Example
```json
{
  "Deals": [
    {
      "Title": "Deal 1",
      "Amount": 1000,
      "OtherProperties": [
        {
          "FieldKey": "custom_field_key",
          "StringValue": "custom value"
        }
      ]
    }
  ]
}
```
```

--------------------------------

### Cities API

Source: https://developers.ploomes.com/index

Endpoints for managing city information, including relationships with countries, states, and cities.

```APIDOC
## GET /api/Cities

### Description
Retrieves a list of cities.

### Method
GET

### Endpoint
/api/Cities
```

```APIDOC
## GET /api/Cities@Countries

### Description
Retrieves cities related to countries.

### Method
GET

### Endpoint
/api/Cities@Countries
```

```APIDOC
## GET /api/Cities@Countries@States

### Description
Retrieves cities related to countries and states.

### Method
GET

### Endpoint
/api/Cities@Countries@States
```

--------------------------------

### Quotes API

Source: https://developers.ploomes.com/index

Endpoints for managing quotes, including approval status and review process.

```APIDOC
## GET /api/Quotes

### Description
Retrieves a list of quotes.

### Method
GET

### Endpoint
/api/Quotes
```

```APIDOC
## POST /api/Quotes

### Description
Creates a new quote.

### Method
POST

### Endpoint
/api/Quotes
```

```APIDOC
## PATCH /api/Quotes({Id})

### Description
Updates an existing quote.

### Method
PATCH

### Endpoint
/api/Quotes({Id
```

--------------------------------

### Contacts API

Source: https://developers.ploomes.com/index

Endpoints for managing contacts and their associated information such as numbers of employees, origins, lines of business, relationships, status, and types.

```APIDOC
## GET /api/Contacts

### Description
Retrieves a list of contacts.

### Method
GET

### Endpoint
/api/Contacts
```

```APIDOC
## POST /api/Contacts

### Description
Creates a new contact.

### Method
POST

### Endpoint
/api/Contacts
```

```APIDOC
## PATCH /api/Contacts({Id})

### Description
Updates an existing contact.

### Method
PATCH

### Endpoint
/api/Contacts({Id})
```

```APIDOC
## DELETE /api/Contacts({Id})

### Description
Deletes a contact.

### Method
DELETE

### Endpoint
/api/Contacts({Id})
```

```APIDOC
## GET /api/Contacts@NumbersOfEmployees

### Description
Retrieves numbers of employees for contacts.

### Method
GET

### Endpoint
/api/Contacts@NumbersOfEmployees
```

```APIDOC
## POST /api/Contacts@NumbersOfEmployees

### Description
Creates a new number of employees entry for a contact.

### Method
POST

### Endpoint
/api/Contacts@NumbersOfEmployees
```

```APIDOC
## PATCH /api/Contacts@NumbersOfEmployees({Id})

### Description
Updates an existing number of employees entry for a contact.

### Method
PATCH

### Endpoint
/api/Contacts@NumbersOfEmployees({Id})
```

```APIDOC
## DELETE /api/Contacts@NumbersOfEmployees({Id})

### Description
Deletes a number of employees entry for a contact.

### Method
DELETE

### Endpoint
/api/Contacts@NumbersOfEmployees({Id})
```

```APIDOC
## GET /api/Contacts@Origins

### Description
Retrieves origins for contacts.

### Method
GET

### Endpoint
/api/Contacts@Origins
```

```APIDOC
## POST /api/Contacts@Origins

### Description
Creates a new origin entry for a contact.

### Method
POST

### Endpoint
/api/Contacts@Origins
```

```APIDOC
## PATCH /api/Contacts@Origins({Id})

### Description
Updates an existing origin entry for a contact.

### Method
PATCH

### Endpoint
/api/Contacts@Origins({Id})
```

```APIDOC
## DELETE /api/Contacts@Origins({Id})

### Description
Deletes an origin entry for a contact.

### Method
DELETE

### Endpoint
/api/Contacts@Origins({Id})
```

```APIDOC
## GET /api/Contacts@LinesOfBusiness

### Description
Retrieves lines of business for contacts.

### Method
GET

### Endpoint
/api/Contacts@LinesOfBusiness
```

```APIDOC
## POST /api/Contacts@LinesOfBusiness

### Description
Creates a new line of business entry for a contact.

### Method
POST

### Endpoint
/api/Contacts@LinesOfBusiness
```

```APIDOC
## PATCH /api/Contacts@LinesOfBusiness({Id})

### Description
Updates an existing line of business entry for a contact.

### Method
PATCH

### Endpoint
/api/Contacts@LinesOfBusiness({Id})
```

```APIDOC
## DELETE /api/Contacts@LinesOfBusiness({Id})

### Description
Deletes a line of business entry for a contact.

### Method
DELETE

### Endpoint
/api/Contacts@LinesOfBusiness({Id})
```

```APIDOC
## GET /api/Contacts@Relationships

### Description
Retrieves relationships for contacts.

### Method
GET

### Endpoint
/api/Contacts@Relationships
```

```APIDOC
## GET /api/Contacts@Status

### Description
Retrieves status options for contacts.

### Method
GET

### Endpoint
/api/Contacts@Status
```

```APIDOC
## GET /api/Contacts@Types

### Description
Retrieves types for contacts.

### Method
GET

### Endpoint
/api/Contacts@Types
```

```APIDOC
## GET /api/Contacts@Products

### Description
Retrieves products associated with contacts.

### Method
GET

### Endpoint
/api/Contacts@Products
```

```APIDOC
## POST /api/Contacts@Products

### Description
Associates a product with a contact.

### Method
POST

### Endpoint
/api/Contacts@Products
```

```APIDOC
## PATCH /api/Contacts@Products({Id})

### Description
Updates the association of a product with a contact.

### Method
PATCH

### Endpoint
/api/Contacts@Products({Id})
```

```APIDOC
## DELETE /api/Contacts@Products({Id})

### Description
Disassociates a product from a contact.

### Method
DELETE

### Endpoint
/api/Contacts@Products({Id})
```

--------------------------------

### PhoneTypes API

Source: https://developers.ploomes.com/index

Endpoint for retrieving phone type information.

```APIDOC
## GET /api/PhoneTypes

### Description
Retrieves a list of phone types.

### Method
GET

### Endpoint
/api/PhoneTypes
```

--------------------------------

### Ploomes API Custom Fields

Source: https://developers.ploomes.com/index

How to create, use, and filter custom fields within Ploomes entities.

```APIDOC
## Custom Fields

*   **Availability**: Some entities support custom fields via the `OtherProperties` property.

*   **Creating a Custom Field**:
    *   Send a POST request to `/Fields`.
    *   The response will contain the `Key` of the newly created field.

*   **Using Custom Fields**:
    *   Include the `FieldKey` and its value within the `OtherProperties` array in your request body.
    *   Example for string and integer values:
      ```json
      {
        "OtherProperties": [
          {
            "FieldKey": "{fieldKey}",
            "StringValue": "example text"
          },
          {
            "FieldKey": "{fieldKey}",
            "IntegerValue": 2
          }
        ]
      }
      ```

*   **Viewing Custom Fields**:
    *   Use the query string `$expand=OtherProperties` in your GET requests.

*   **Filtering by Custom Fields**:
    *   For performance, filter using the `FieldId` instead of `FieldKey`. You can find the `FieldId` by querying the `/Fields` endpoint and filtering by the field's key.
    *   Example filtering by a text field with `FieldId` 245552 and value 'teste':
      ```
      https://api2.ploomes.com/Deals?filter=((((OtherProperties/any(o:+o/FieldId+eq+245552+and+(o/StringValue+eq+'teste'))))))
      ```
```

--------------------------------

### Ploomes API Custom Field Handling

Source: https://developers.ploomes.com/index

Demonstrates how to structure the JSON payload to include custom field data when creating or updating records via the Ploomes API. It shows how to map custom fields using 'FieldKey' and specifying the value type (e.g., StringValue, IntegerValue).

```json
{
 "OtherProperties": [
 {
 "FieldKey": "{fieldKey}",
 "StringValue": "texto exemplo"
 },
 {
 "FieldKey": "{fieldKey}",
 "IntegerValue": 2
 }
 ]
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.