openapi: 3.0.0
info:
  title: Custify App
  description: |
    This is the documentation for APIs from the Custify App.
    # INTRODUCTION
    The Custify API is a RESTful API. The requests and responses are formatted according to the JSON API specification.

    It might happen that you requested to run your Custify application within a data center that's optimized for your location. In this case, you might have to use a different API endpoint URL, instead of https://api.custify.com, to optimize your calls. You'll find your API URL within the app at [Settings -> Developers -> API Key](https://app.custify.com/settings/developer/api-key).
    ### Data imports
    In general, there are 3 ways to synchronize your customer data and their events with Custify *on an ongoing basis*:
    - The Custify API
    - The Custify JavaScript snippet
    - An available integration with one of your systems (e.g., via Segment.com)

    This documentation covers the Custify API and JavaScript snippet. Individual integrations are documented separately.

    For the *initial* data import, you have several options:
    - Write a script that uses the Custify API to run through your customers and call the API for each one of them
    - An available integration into one of your systems that pulls the customer data from there (e.g., Hubspot)

    ### Data types
    The data type of the first submission (import or API request) defines the data type of an attribute or event metadata within Custify (Boolean, Integer, Date, or String). We'll try to auto-detect the type of the attribute (or event metadata) in the following order: Date, Number and Boolean.
    If none of these types will match the type of the attribute will be set to String.

    For an attribute or event metadata to be detected as Date it should be sent in the following ISO 8601 formats: `YYYY-MM-DD HH:mm:ss`, `YYYY-MM-DD`, `YYYY-MM-DDTHH:mm:ss`, `YYYY-MM-DD HH:mm`, `YYYY-MM-DDTHH:mm:ss.SSS`, `YYYY-MM-DDTHH:mm:ssZ`, `YYYY-MM-DDTHH:mm:ss.SSSZ` or `YYYY-MM-DDTHH:mm:ss.SSSSSSZ`.
    Otherwise, they'll be treated as Strings. These attributes must be sent as UTC dates or using the timezone format. Example:
    ```json
    {
        "company_id": "25",
        "custom_attributes": {
            "date": "2020-09-25T10:00:00",
            "date_format": "2020-09-25T10:00:00.000"
        }
    }
    ```

    For an attribute (or event metadata) to be detected as a Number you could send it as in the following example:
    ```json
    {
        "company_id": "25",
        "custom_attributes": {
            "team_mates": 5,
            "team_mates_number": "7",
            "also_number": 10.2,
            "other_number": "5.4"
        }
    }
    ```

    For an attribute (or event metadata) to be detected as a Boolean you could send it as in the following example:
    ```json
    {
        "company_id": "25",
        "custom_attributes": {
            "unsubscribed": true,
            "unsubscribed_false": "FALSE"
            "unsubscribed_true": "true"
        }
    }
    ```

    This initial data type is later used to compare attributes of different entities (e.g., when creating segments or searching). Although you can send a different data type later on, the first submission defines the data type that Custify uses for this field. We highly recommend never switching the data type for your custom attributes. If you need to change it, submit a new attribute for all customers with the new data type.

    You can also set values to null. You might do this, for example, if you no longer have a valid value for one of your attributes.

    ### Rate limiting
    The API may limit the submission of requests for your application. The limits are managed as an allowed number of operations per time window; an operation might be a read or an update. If you're not on a special enterprise plan, API calls are limited to `100 requests` per `10 seconds` time window. If the limit is reached, a `429 Too Many Requests` response code will be returned along with the following headers:

    #### Rate limit headers:
    - `X-RateLimit-Limit`: Maximum number of operations allowed in the current window
    - `X-RateLimit-Remaining`: Number of operations left in the current window.
    - `Retry-After`: Number of seconds starting from the first request in the window after the rate limit window will be reset.

    Further limitations on certain objects (like the maximum length of strings, range of integers) are documented in the individual API calls.

    ### Postman collection
    Postman is a tool that lets you build and test HTTP requests in an easy-to-use interface without configuring a full development environment. The Custify Postman Collection is a set of preconfigured requests that make it possible to get started with the Custify API from Postman without having to manually configure the requests.
    You can download the collection from here => (<a href="postman_collection.json" download>POSTMAN collection</a>). To use the collection you can create a new environment (let's say `Custify`) and create the 2 needed variables `ApiUrl` and `ApiKey` which are available here [Settings -> Developers -> API Key](https://app.custify.com/settings/developer/api-key).

    # AUTHENTICATION
    ### API
    When you sign up for an account, you're given your account ID. This ID is visible within [Settings -> Developers -> API Key](https://app.custify.com/settings/developer/api-key). *Never share the API key and only use the API key for API calls, not for JavaScript calls*. Keep it guarded and secure, *as anyone with this key will have full read and write access to your data*.

    You authenticate to the Custify API by providing your API key in the request header (`Authorization: Bearer <API_KEY>`).
    <security-definitions />
    ### JavaScript snippet
    When you sign up for an account, you're given your account ID. This ID will be visible to you within the Settings -> Developer section.
    # JAVASCRIPT
    We offer an easy and fast integration via a JavaScript snippet, a block of code you can insert in pages of your app. It's a fast way to send data to the Custify app and the ideal way to track events like clicked buttons or menu items and/or to track time spent in your product.
    ## Send data using the JavaScript snippet
    The JavaScript snippet is a low-impact way to send data to [api.custify.com](https://api.custify.com). While an API integration is more flexible, this is a quick way to get started.

    ### How to use the JavaScript snippet to send data

    #### Step 1: Add the basic JavaScript
    On every page that you want to track events (e.g., button clicks) or to track the time spent in the product, include the script found at [Settings -> Developers -> JS snippet](https://app.custify.com/settings/developer/js-snippet) just before the closing </body> tag.

    #### Step 2: Identify your account and the user
    Every event within your application  (e.g., “button clicked” or “login”) or the time spent in product is generated from a specific user. For Custify to know which of the users it should attribute the event(s) to, you need to specify the user with an ID and/or email address before sending an event.
    If the user is part of one or more companies you can link the event to a specific company using the attribute company_id. This attribute is optional.
    - The user ID is referenced in the code below as `USER_ID` and represents the unique ID of the user *within your systems/CRMs*. It's part of the API call to create that user in the first place.
    - The email is referenced as `USER_EMAIL` and represents the unique email of the user within your systems/CRMs.
    - The company is referenced as `COMPANY_ID` and represents the unique ID of the company within your systems/CRMs.

    For the identification of the account and user, you need to add the identification function to your code *beneath the aforementioned basic Javascript*:
    ```javascript
    <script type="text/javascript">
        _ctrack.identify({
            userId: 'USER_ID', // Your Id of the user
            email: 'USER_EMAIL', // Email of the user
            company_id: 'COMPANY_ID' // Your Id of the company
        });
    </script>
    ```
    Custify recommends that you use both userID and email to ensure that users can be identified correctly. The user must already exist in your Custify application before you send events through the JavaScript snippet.

    #### Step 3: Track events
    Simple page view tracking can be done by the following snippet:
    ```javascript
    <script type="text/javascript">
        _ctrack.track("EVENT_NAME", {
          "METADATA1": "VALUE1",
          "METADATA2": "VALUE2",
          ...
        });
    </script>
    ```
    Event tracking (i.e., after a button click) can be done using the following snippets as examples:

    *pure Javascript*

    ```html
    <button onclick='_ctrack.track("EVENT_NAME", {"METADATA1": "VALUE1", "METADATA2": "VALUE2", ...});'>Button</button>
    ```

    *using jQuery*
    ```javascript
    <script src="jquery-3.3.1.min.js"></script>
    <script type="text/javascript">
      $(document).ready(function () {
          $('#button').click(function () {
              _ctrack.track("EVENT_NAME", {
                "METADATA1": "VALUE1",
                "METADATA2": "VALUE2",
                ...
              });
          });
      });
    </script>
    ```
    *The second parameter of the `track` function should be a JSON object carrying the additional metadata for that specific event*.

    One possible example for a tracked event would be this:
    ```javascript
    _ctrack.track("Checkout complete", {
                "Item1": "4$",
                "Item2": "7$"});
    ```

    #### Step 4: Track time spent in your product
    Tracking the time spent on a page can be done using the following snippet:
    ```javascript
    <script type="text/javascript">
        _ctrack.trackTime(true,
            {
              module: 'blog'
            }
        );
    </script>
    ```
    where `module` represents the name you give to that specific page. The time in product for a user is tracked if one of the actions is detected: mouse move, click, scroll or keyboard input. If in the default idle time of `60` seconds no action is detected the tracking of time is stopped.
    The default idle time can be changed by adding a new field in the JSON object for the `trackTime` function:
    ```javascript
    <script type="text/javascript">
        _ctrack.trackTime(true,
            {
              module: 'blog',
              idleTimer: 30
            }
        );
    </script>
    ```
    On pages that you don't want to track the time don't include the function `trackTime`. If your application is a SPA (single-page application) and you don't want to track a specific page you'll have to stop the tracking using the function `stopTrackTime`:
    ```javascript
    <script type="text/javascript">
        _ctrack.stopTrackTime();
    </script>
    ```
    
    #### Step 5: Create or update people / companies
    In order to be able to the create/update people and/or companies through the JS snippet 2 different options have to be turned on:
    - one is from within the app at [Settings -> Developers -> JS snippet](https://app.custify.com/settings/developer/js-snippet) where you have to toggle ON the setting `Allow creating/updating people and companies via the JS snippet`, otherwise calls will be rejected with a HTTP 403 Forbidden code
    - one in the JS snippet code where you need to set the `createOrUpdateEntities` to `true` via the `setOptions` method **before** doing the `identify` call
      ```javascript
      <script type="text/javascript">
          _ctrack.setOptions({
              “createOrUpdateEntities”: true
          });
      </script>
      ```
    
    In order to send entities to Custify, you need to amend the `_ctrack.identify()` call as it follows - adding the 2nd parameter to the call, where you include the entity attributes:

    ```
    _ctrack.identify(
      {
          userId: 'USER_ID', // Your Id of the user
          email: 'USER_EMAIL', // Email of the user
          company_id: 'COMPANY_ID' // Your Id of the company
      },
      {
          // The People entity within Custify
          user: {
              name: "John Doe",
              email: 'john.doe@example.com', //if provided will overwrite the one on top, if not we use the one on top
              unsubscribed_from_emails: false, //example of default attribute
              custom_attributes: { //an object of custom_attributes, as described in the People Creation API
                  attr_1: "test",
                  attr_2: 123,
                  ...
              }
          },
          // The Company entity within Custify
          company: {
              name: "ACME Corporation",
              monthly_revenue: 10000,
              custom_attributes: {
                  has_employees: false,
                  employees_number: 0,
                  owner: "Road Runner",
                  ...
              }
          }
      }
    );
    ```

    If a `company` entity will be sent, then a Company record will be created or updated, depending on the `company_id` provided. If a `user` entity will be sent, then a People record will be created or updated, depending on the `user_id` provided. If there is a `user` entity sent and also a `company_id` specified in the first parameter of the identify call, then the user will be linked to that company (if it exists), no matter if a `company` entity is also provided or not.
    
    #### Step 6: Trigger in-app survey
    In order to be able to trigger a in-app survey in your application through the JS snippet following things must happen:
    - update/install your JS snippet code to the latest version so that you can call the new functions `triggerPendingAction` and `closePendingAction` like in [Settings -> Developers -> JS snippet](https://app.custify.com/settings/developer/js-snippet)
    - request your CSM to get activated this option
    - after this option is activated for your account you can define a playbook that triggers the in-app survey step for certain companies/people
    - on the pages where you want to display the in-app survey, just trigger the `triggerPendingAction` function of the JS Snippet as such `_ctrack.triggerPendingAction()`, which will check the Custify backend for any actions available for the previously identified user (and company) that were set through the `_ctrack.idenfify()` call. Can be triggered on a page load or on a button click (or any valid action).
    - the HTML code of the in-app area has the following structure, but the exact styles (which are added inline) depend on the settings made in the Playbook step (where you can select the survey placement, the number of times it will be displayed and the number of days the survey will be available):
    ```
    <div class="custify-in-app-container-outter">
      <div class="custify-in-app-container-inner">
        <iframe class="custify-in-app-iframe"></iframe>
        <div class="custify-in-app-close">Close</div>
      </div>
    </div>
    ```
    - if you want, you can further customize the look, feel and placement of the survey using the CSS classes provided, but for some properties using `!important` might be required.
  termsOfService: https://www.custify.com/terms
  contact:
    name: API Support
    url: https://www.custify.com/contact
    email: contact@custify.com
  x-logo:
    url: https://docs.custify.com/images/logo.png
  license:
    name: Privacy Policy
    url: https://www.custify.com/privacy
  version: 1.5.7
servers:
  - url: https://api.custify.com
    description: Production server
tags:
  - name: People
    x-displayName: "PEOPLE"
    description: |
      People are the individual users within your application. They usually have a name and attributes like “email address,” “phone,” etc.

      You can create, update, and delete people and add or update custom attributes describing them. Customers can be viewed individually or as a list.

      ### Limitations
      - Any integer values in the customer model are limited to the int32 range (-2^31 to 2^31-1).
      - Fields of the type String are limited to 255 characters.

      ### Custom attributes
      The custom_attributes object allows you to send any information you wish about a customer with the following restrictions:
      - Field names must not contain periods (`.`) or dollar (`$`) characters.
      - Field names must be no longer than 190 characters.
      - Field names must not contain only numbers.
      - Field values must be JSON Strings, Numbers or Booleans; Objects and Arrays will be rejected.
      - String field values must be no longer than 255 characters.
      - Maximum of 250 fields.
      - Custom attribute as a Date: send it in one of the Date formats described earlier. If the name of your custom attribute ends with "_at," we'll automatically treat it as a Date rather than a String.

      ### Unsetting attributes
      The custom attributes and some of the default attributes (`name`, `phone`, `signed_up_at`, `session_count`, `unsubscribed_from_emails`, `unsubscribed_from_calls`) can be unset from a people. An example of request could look like:
      ```json
      {
        "user_id": "123",
        "$unset": ["plan", "custom_attributes.int_team_mates"]
      }
      ```
      The people can be identified using the fields `id` (Custify internal ID), `user_id` (your internal ID of the people) or the `email`. The field `$unset` should be an array of strings representing the field names you want to unset using the dot(`.`) notation.
      In the same request you can set and/or unset fields. Also you cannot set and unset the same field in a request.
  - name: Event
    x-displayName: "EVENTS"
    description: |
      Events are generated by your users (“people” within Custify) while they use your application. You can also send “company-only” events, which are not related to a particular person. Events can be things like “printed an invoice,” or “logged into the platform,” and represent an activity that a user is performing within your application.
      You can track as many events as you wish, although we recommend focusing on the relevant ones for your business. Events are an essential part of the logic within Custify, and only if you track all relevant events will you be able
      to create proper segments, monitor customer lifecycles, and automate your customer success workflows properly. If there's an event for your user and the user is part of one or more companies you can link the event also to a specific company.

      ### Limitations
      - Any integer values in the event model are limited to the int32 range (-2^31 to 2^31 -1).
      - Fields of the type String are limited to 100 characters.
      - Each event can contain up to `50` metadata key values.
      - Metadata object is limited to 10,000 characters.
  - name: Company
    x-displayName: "COMPANIES"
    description: |
      Companies represent commercial entities using your product, and they bundle people together within one organization. Companies typically have names like “ACME Ltd” or “Big Cooperation ABC,” and have attributes like “plan,” “monthly revenue,” “website” etc. You can create and update companies and add custom attributes describing them.
      Besides the pre-defined (mostly optional) attributes, Custify offers you the option to add any kind of custom attributes to companies. These will all be visible within the application later on. Examples would be "generated revenue," "payment plan," "address," or "primary contact."
      The “churned” attribute is a special attribute used to indicate that this customer left you and can later be used within Custify to build segments and learn specific behaviors of such customers. Although optional, it can be a good addition to your set of data.

      ### Limitations
      - Any integer values in the company model are limited to the int32 range (-2^31 to 2^31-1).
      - Fields of the type String are limited to 255 characters.

      ### Custom attributes
      The custom_attributes object allows you to send any information you wish about a company with the following restrictions:
      - Field names must not contain periods (`.`) or dollar (`$`) characters.
      - Field names must be no longer than 190 characters.
      - Field names must not contain only numbers.
      - Field values must be JSON Strings, Numbers or Booleans; Objects and Arrays will be rejected.
      - String field values must be no longer than 255 characters.
      - Maximum of 250 fields.
      - Custom attribute as a Date: send it in date one of the Date formats described earlier. If the name of your custom attribute ends with "_at", we'll automatically treat it as a Date rather than a string.

      ### Unsetting attributes
      The custom attributes and some of the default attributes (`name`, `plan`, `signed_up_at`, `owners_csm`, `owners_account`, `size`, `website`, `industry`, `monthly_revenue`) can be unset from a company. An example of request could look like:
      ```json
      {
        "company_id": "123",
        "$unset": ["plan", "custom_attributes.int_team_mates"]
      }
      ```
      The companies can be identified using the fields `id` (Custify internal ID) or `company_id` (your internal ID of the company). The field `$unset` should be an array of strings representing the field names you want to unset using the dot(`.`) notation.
      In the same request you can set and/or unset fields. Also you cannot set and unset the same field in a request.
  - name: Note
    x-displayName: "NOTES"
    description: |
      Notes allow you to annotate and comment on your people or companies.
  - name: Tag
    x-displayName: "TAGS"
    description: |
      A tag allow you to label your people.
  - name: CustomData
    x-displayName: "CUSTOM DATA"
    description: |
      Custom data objects stored on Companies or People
  - name: NPSScore
    x-displayName: "NPS SCORE"
    description: |
      Assign a NPS score to a people.
  - name: CSATScore
    x-displayName: "CSAT SCORE"
    description: |
      Assign a CSAT score to a people.
  - name: Batch
    x-displayName: "BATCH"
    description: |
      Send batch requests for creating/updating people, companies, events or custom data.
  - name: Tickets
    x-displayName: "TICKETS"
    description: |
      Create, update and delete tickets on Companies or People.
  - name: Tasks
    x-displayName: "TASKS"
    description: |
      Create, update and list tasks on Companies.
  - name: Comments
    x-displayName: "COMMENTS"
    description: |
      Create, update and list comments on Notes and Tasks.
  - name: Financial Deals
    x-displayName: "FINANCIAL DEALS"
    description: |
      Create, update, list and delete financial deals.
  - name: Financial Invoices
    x-displayName: "FINANCIAL INVOICES"
    description: |
      Create, update, list and delete financial invoices.
  - name: Financial Subscriptions
    x-displayName: "FINANCIAL SUBSCRIPTIONS"
    description: |
      Create, update, list and delete financial subscriptions.
  - name: Files
    x-displayName: "FILES"
    description: |
      Upload files, link files to a task or note, unlink files and list files for an entity (company or people). If you want to link an uploaded file to a task or to a note please use the field `files` (providing a list of file ids) available in the create/update methods for each of the operations.
  - name: Surveys
    x-displayName: "SURVEYS"
    description: |
      List surveys and retrieve survey responses. Use the list endpoint to get all your surveys, then use the responses endpoint to export the individual responses for a specific survey.
  - name: Time Tracking
    x-displayName: "TIME TRACKING"
    description: |
      Create, update, delete and list time tracking entries.
  - name: Meetings
    x-displayName: "MEETINGS"
    description: |
      Create, update, delete and list meetings on Companies or People.
  - name: Calculated Metrics
    x-displayName: "CALCULATED METRICS"
    description: |
      List calculated metrics.
  - name: Health Scores
    x-displayName: "HEALTH SCORES"
    description: |
      List health scores.
  - name: Segments
    x-displayName: "SEGMENTS"
    description: |
      List segments.
  - name: Lifecycles
    x-displayName: "LIFECYCLES"
    description: |
      List lifecycles and their goals, tasks, and configuration.
  - name: Playbooks
    x-displayName: "PLAYBOOKS"
    description: |
      List playbooks and their steps, triggers, and configuration.
  - name: Customer Objectives
    x-displayName: "CUSTOMER OBJECTIVES"
    description: |
      List customer objectives for a specific company. Objectives track goals set for customers, including their completion status, importance, risk level, and progress.
  - name: Person-Company Relationships
    x-displayName: "PERSON-COMPANY RELATIONSHIPS"
    description: |
      A person can belong to more than one company, and the same person can hold a different **role** in each of them (for example "Admin" at one company and "Billing Contact" at another). A person-company relationship stores the role and any relationship-specific custom attributes for one person at one company.

      ### Enabling the feature
      These endpoints are only available when **company-dependent people roles** are enabled for your account, under [Settings → General](https://app.custify.com/settings). If the feature is disabled, every relationship endpoint responds with `403` and the message `Company-dependent people roles are not enabled for this account.`

      ### The relationship object
      A relationship links one person to one company (a person must already be linked to the company before a relationship can be created). It exposes the following fields:
      - `person` — the Custify internal `id` of the person.
      - `company` — the Custify internal `id` of the company.
      - `role` — the person's role at that company. Must be one of the role values configured for your account; sending an unconfigured value returns `400`. Pass `null` to clear the role.
      - `linked_at` — optional date marking when the person joined the company. Set only on creation.
      - `custom_attributes` — relationship-specific custom attributes. Each key must match a configured `people-company-attribute`; unknown keys return `400`.
      - `created_at`, `updated_at` — timestamps managed by Custify.

      A given person can have at most one relationship per company.
paths:
  /people:
    post:
      summary: Create or update people
      description: |
        People can be created or updated via a POST method to [https://api.custify.com/people](https://api.custify.com/people), which accepts a JSON object describing the people. People not found via email or user_id will be created, and those found will be updated if one of the attributes contains a new value or if you add a new attribute.

        Note that the following lookup order applies when updating people: first `id` (Custify internal ID), then `user_id` (your internal ID of the person), then `email`. This results in the following logic:
        - `id` is matched: the `user_id` and `email` will be updated if they"re sent
        - `user_id` match: the `email` will be updated, the `id` is not updated
        - `email` match where no `user_id` set on the matching user: the `user_id` will be set to the value sent in the request, the `id` is not updated
        - `email` match where there is a `user_id` set on the matching user: a new unique record with new `id` will be created if a new value for `user_id` is sent in the request.

        ### Associate people with a company
        The assignment of people to companies should be done as soon as possible in your process; ideally right after creating the person entry. Once people are assigned to a company, the events they generate are also associated with that company.
        To associate a company with a customer, send a POST request with the following JSON body:
        ```json
        {
          "id": "531ee472cce572a6ec000005",
          "companies": [
            {
              "company_id" : "366"
            }
          ]
        }
        ```
        where `company_id` is *your internal ID* of the company and was specified through the company API call before. If you want to use the Custify internal ID, send a POST with the following JSON body:
        ```json
        {
          "id": "531ee472cce572a6ec000005",
          "companies": [
            {
              "id" : "531ee472cce572a6ec000006"
            }
          ]
        }
        ```

        ### Remove people from a company
        To remove people from a company, send a POST request with the following JSON body:
        ```json
        {
          "id": "531ee472cce572a6ec000005",
          "companies": [
            {
              "company_id" : "3",
              "remove" : true
            }
          ]
        }
        ```
        where `company_id` is *your internal ID* of the company and was specified through the company API call before. If you want to use the Custify internal ID, send a POST with the following JSON body:
        ```json
        {
          "id": "531ee472cce572a6ec000005",
          "companies": [
            {
              "id" : "531ee472cce572a6ec000006",
              "remove" : true
            }
          ]
        }
        ```
      parameters: [
        {
          $ref: "#/components/parameters/resourceIdOptional"
        },
        {
          $ref: "#/components/parameters/userIdParam"
        },
        {
          $ref: "#/components/parameters/emailParam"
        }
      ]
      responses:
        '200':
          description: 'Successful operation'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/People"
        description: Created people object
        required: true
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/people' \\\n
          -X POST \\\n
          -H 'Authorization: Bearer <Your access token>' \\\n
          -H 'Accept: application/json' \\\n
          -H 'Content-Type: application/json' -d '\n{\n  \"user_id\": \"25\",\n  \"email\": \"john.doe@mail.com\",\n  \"phone\": \"+44 7911 123456\",\n  \"signed_up_at\": \"2019-05-30T12:00:00.000Z\",\n  \"name\": \"John Doe\",\n  \"session_count\": 2,\n  \"custom_attributes\": {\n    \"bool_paid_subscriber\": true,\n    \"int_team_mates\": 5,\n    \"string_plan\": \"advanced\",\n    \"date_example_date_at\": \"2019-06-30T12:00:00.000Z\"\n  },\n  \"unsubscribed_from_emails\": false,\n  \"unsubscribed_from_calls\": false\n }'"
      tags: [ "People" ]
    delete:
      summary: Delete people
      description: |
        People can be deleted by sending a DELETE request to the entry's URL using the Custify *id* field as part of the path
        - `https://api.custify.com/people/{id}`

        Alternatively, you can delete people by sending a DELETE request using the *email* or *user_id* as query parameters
        - `https://api.custify.com/people?email={email}`
        - `https://api.custify.com/people?user_id={user_id}`

        Note that this function permanently deletes any records, such as events, and any other data within Custify. It also represents the GDPR compliance on your end and our end. You have to call this function if a person requests to be deleted from all your records ("forget me").
      parameters: [
        {
          $ref: "#/components/parameters/resourceIdOptional"
        },
        {
          $ref: "#/components/parameters/userIdParam"
        },
        {
          $ref: "#/components/parameters/emailParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/people?user_id=123' \\\n
                -X DELETE \\\n
                -H 'Authorization: Bearer <Your access token>' \\\n
                -H 'Accept: application/json' \\\n
                -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (invalid request syntax)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      tags: [ "People" ]
  "/people/{id}":
    get:
      summary: View people
      description: |
        You can view people’s details by sending a GET request to [https://api.custify.com/people/{id}](https://api.custify.com/people/{id}), where {id} is the value of the person's `id` field. 
        People can also be fetched using a `user_id` or `email` parameter in the URL. If you want to apply filters to the response from `/people/{id}` endpoint, you would need to send the `properties` query parameter as an URL-encoded array of fields to be returned.
        Some default properties are available for all entities: `id`, `name`, `created_at` and `updated_at`.
      parameters: [
        {
          $ref: "#/components/parameters/resourceIdOptional"
        },
        {
          $ref: "#/components/parameters/userIdParam"
        },
        {
          $ref: "#/components/parameters/emailParam"
        },
        {
          $ref: "#/components/parameters/includeSegmentsParam"
        },
        {
          $ref: "#/components/parameters/filteringProperties"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/people/5d1eea314ce8477adf5af46c' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          description: Param provided is missing or invalid
        '500':
          description: Some other error occurred
      tags: [ "People" ]
  "/people/all":
    get:
      summary: List people
      description: |
        You can fetch a list of people. The list, by default, is sorted by the `signed_up_at` field and in `descending` order, with the most recent signups first.
        ### Filtering people
        If you want to apply filters to the `/people/all` endpoint, you would need to send the `filters` query parameter as an URL-encoded array of objects. You can follow the steps described when filtering [Companies](#tag/Company/paths/~1company~1all/get).
        ### Filtering properties
        If you want to apply filters to the response from `/people/all` endpoint, you would need to send the `properties` query parameter as an URL-encoded array of fields to be returned.
        Some default properties are available for all entities: `id`, `name`, `created_at` and `updated_at`.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax200"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        },
        {
          $ref: "#/components/parameters/filteringParam"
        },
        {
          $ref: "#/components/parameters/includeSegmentsParam"
        },
        {
          $ref: "#/components/parameters/filteringProperties"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/people/all?itemsPerPage=10&page=7' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "People" ]
  "/people/tag":
    post:
      summary: Add/remove tag to/from a people
      description: Adding or removing a tag to or from a people. To add the tag you'll need to send the `type="add"` and for removing you'll need to send the `type="remove"`.
      responses:
        '200':
          description: 'Successful operation'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/PeopleTag"
        description: Add/remove tag to/from a people object
        required: true
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/people/tag' \\\n
                -X POST \\\n
                -H 'Authorization: Bearer <Your access token>' \\\n
                -H 'Accept: application/json' \\\n
                -H 'Content-Type: application/json' -d '\n{\n  \"ids\": [\"5d402cf8c3a4c5578c9be5f4\", \"5d11c88ca6674a2541ade9b8\"],\n  \"type\": \"add\",\n  \"tag\": \"5d948817c5f9442ea5482321\"\n }'"
      tags: [ "People" ]
  "/event":
    post:
      summary: Insert events
      description: |
        Submit events via a POST method to https://api.custify.com/event, which accepts a JSON object describing the event.

        Note that the following lookup order applies when inserting events for a people: `user_id` then `email`. This results in the following logic:
         - `user_id` match: the `email` will be ignored if it is passed.
         - `email` match: the `user_id` is missing.

        If submitting events for a people the company ID field is optional, it is only needed if you have people that are assigned to several companies at the same time. Use it then, to specify the company that this event should be counted for.

        When submitting “company-only” events you have to specify the `company_id` field. The `user_id` field should not be present in this case.
      responses:
        '202':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          description: People not found
        '500':
          description: Some other error occurred
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/event' \\\n
                -X POST \\\n
                -H 'Authorization: Bearer <Your access token>' \\\n
                -H 'Accept: application/json' \\\n
                -H 'Content-Type: application/json' -d ' \n{\n  \"name\": \"login\",\n  \"created_at\": \"2019-05-30T12:00:00.000Z\",\n  \"user_id\": \"1\",\n  \"email\": \"test@example.org\",\n \"deduplication_id\": \"5d95ecc9749204521d2e7945\",\n  \"metadata\": {\n    \"email\": \"john@example.org\",\n    \"code\": \"ABCDEF\"\n  }\n}'"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Event"
        description: Created event object
        required: true
      tags: [ "Event" ]
  "/company":
    post:
      summary: Create or update a company
      description: |
        Companies can be created or updated via a POST to https://api.custify.com/company, which accepts a JSON object describing the company.
        Companies are looked up via `id` or `company_id` - if it's not found via both parameters, the new company will be created. If a company is found, it will be updated.

        Note that the `company_id` field itself cannot be updated through the API.
        
        When submitting custom attributes of type `User` you can specify the Custify internal ID of the user or the email address. Examples:
        ```json
        {
          "company_id": "1",
          "custom_attributes": {
            "user_type_field": "531ee472cce572a6ec000006"
          }
        }
        ```
        or
        
        ```json
        {
          "company_id": "1",
          "custom_attributes": {
            "user_type_field": "john.doe@example.com"
          }
        }
        ```

        ### Associate a company with another company
        Once a company is assigned to another company, the events generated by the people that are part of the "child" company are also associated with the "parent" company.
        To associate a company with another company, send a POST request with the following JSON body:
        ```json
        {
          "company_id": "1",
          "parent_companies": [
            {
              "company_id" : "2"
            }
          ]
        }
        ```
        where `company_id` is *your internal ID* of the company and was specified through the company API call. If you want to use the Custify internal ID, send a POST with the following JSON body:
        ```json
        {
          "company_id": "1",
          "parent_companies": [
            {
              "id" : "531ee472cce572a6ec000006"
            }
          ]
        }
        ```

        ### Remove a company from 'parent_companies' of another company
        To remove a company from 'parent_companies' of another company, send a POST request with the following JSON body:
        ```json
        {
          "company_id": "1",
          "parent_companies": [
            {
              "company_id" : "2",
              "remove" : true
            }
          ]
        }
        ```
        where `company_id` is *your internal ID* of the company and was specified through the company API call. If you want to use the Custify internal ID, send a POST with the following JSON body:
        ```json
        {
          "company_id": "1",
          "companies": [
            {
              "id" : "531ee472cce572a6ec000006",
              "remove" : true
            }
          ]
        }
        ```
        
        ### Insert/update a field of type 'Currency'
        To insert/update a field of type 'Currency', send a POST request with the following JSON body:
        ```json
        {
          "company_id": "1",
          "custom_attributes": {
              "currency_field": {
                "value": 100,
                "currency": "USD"
              }
          }
        }
        ```
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          description: Company not found
        '500':
          description: Some other error occurred
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/company' \\\n
                      -X POST \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json' -d ' \n{\n  \"company_id\": 6,\n  \"name\": \"Pizzeria Presto\",\n  \"signed_up_at\": \"2019-05-30T12:00:00.000Z\",\n  \"size\": 15,\n  \"website\": \"www.pizzeriapresto.com\",\n  \"industry\": \"Restaurant\",\n  \"monthly_revenue\": 1234567,\n  \"churned\": false,\n  \"custom_attributes\": {\n    \"restaurants\": 5,\n    \"custom\": \"template\"\n  }\n}'"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Company"
        description: Created company object
        required: true
      tags: [ "Company" ]
    delete:
      summary: Delete company
      description: |
        Companies can be deleted by sending a DELETE request to the entry's URL using the Custify *id* field as part of the path
        - `https://api.custify.com/company/{id}`

        Alternatively, you can delete a company by sending a DELETE request using the *company_id* as query parameter
        - `https://api.custify.com/company?company_id={company_id}`

        Note that this function permanently deletes any records, such as events, and any other data within Custify. It also represents the GDPR compliance on your end and our end. You have to call this function if a company requests to be deleted from all your records ("forget me").
      parameters: [
        {
          $ref: "#/components/parameters/resourceId"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/company/5d1eea314ce8477adf5af46c' \\\n
                    -X DELETE \\\n
                    -H 'Authorization: Bearer <Your access token>' \\\n
                    -H 'Accept: application/json' \\\n
                    -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (invalid request syntax)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      tags: [ "Company" ]
  "/company/{id}":
    get:
      summary: View company
      description: |
        You can view a company’s details by sending a GET request to [https://api.custify.com/company/{id}](https://api.custify.com/company/{id}), where {id} is the value of the company's `id` field. Companies can also be fetched using a `company_id` parameter in the URL.
        If the company has set user type attributes, like the default ones `owners_csm` or `owners_account`, or user defined attributes, like `user_type_field`, those will be enhanced in the response with the email and the name of the user, like `{attribute}_email` and `{attribute}_name`.
        If the user above has set `user custom attributes` those will be enhanced in the response with the value of the custom attribute, like `{attribute}_attributes`, if you'll pass in the query params of the request the field `includeUserAttributes` with the value of `true`. This field will be of type `object` and will contain all the custom attributes of the user.
        If you want to apply filters to the response from `/company/{id}` endpoint, you would need to send the `properties` query parameter as an URL-encoded array of fields to be returned.
        Some default properties are available for all entities: `id`, `name`, `created_at` and `updated_at`.
      parameters: [
        {
          $ref: "#/components/parameters/resourceIdOptional"
        },
        {
          $ref: "#/components/parameters/companyIdParam"
        },
        {
          $ref: "#/components/parameters/includeSegmentsParam"
        },
        {
          $ref: "#/components/parameters/filteringProperties"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/company/5d26f09c5c629e342bf47ff3' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          description: Param provided is missing or invalid
        '500':
          description: Some other error occurred
      tags: [ "Company" ]
  "/company/all":
    get:
      summary: List companies
      description: |
        You can fetch a list of companies. The list, by default, is sorted by the `signed_up_at` field and in `descending` order, with the most recent signups first.
        ### Filtering companies
        If you want to apply filters to the `/company/all` endpoint, you would need to send the `filters` query parameter as an URL-encoded array of objects as follows:
        ```json
          [
              {
                fieldName: "name",
                fieldType: "String",
                filterType: "contains",
                filterValue: "a"
              }
          ]
        ```

        The operator used between the different conditions passed will be **AND**, so the returned entities must fulfill all the conditions sent in the filters array. Also, the same field can be sent multiple times if for example you want to filter for names that start with A and also contain XY.

        For the `fieldName` property, you should send it formatted as it follows:
        - If it is a default attribute, send just the name: `name`, `size`, `created_at`, `owners_csm`, etc
        - If it is a custom attribute, send it using dot-notation, as follows: `custom_attributes.myAttribute`, `custom_attributes.deal_stage`, etc
        - If you want to filter by tag, sent the name `tags`
        - If you want to filter by a calculated metric, sent it as `metrics.calculated_metrics.CALCULATED_METRIC_ID`, example `metrics.calculated_metrics.5fa5b24f584088153f7fd825`
        - If you want to filter by a health score, send it as `metrics.health_scores.HEALTH_SCORE_ID`, example `metrics.health_scores.5f86fee26e8f7c489b28dd03`

        Possible values for `fieldType`, with associated values for the other properties as well:
        - **Number**:
            - Available for all numerical default and custom attributes as well as calculated metrics and health scores and has the following possible `filterType` values:
                - `greater` - the value of the attribute/metric is greater than the value provided in the `filterValue` field
                - `lower` - the value of the attribute/metric is lower than the value provided in the `filterValue` field
                - `is` - the value of the attribute/metric is equal to the value provided in the `filterValue` field
                - `is_not` - the value of the attribute/metric is different from the value provided in the `filterValue` field
                - `is_unknown` - the attribute/metric does not exist on the entity. The `filterValue` can be sent as either NULL or empty string
                - `any_value` - the attribute/metric exists on the entity and has any value. The `filterValue` can be sent as either NULL or empty string
            - If the `fieldName` is a health score, there are 3 additional `filterType` options that can be used. For all of them the `filterValue` should be either an empty string or NULL:
                - `is_bad` - the health score is bad, meaning the value of the health score is in the red area as defined in the health score settings
                - `is_average` - the health score is average, meaning the value of the health score is in the orange area as defined in the health score settings
                - `is_good` - the health score is good, meaning the value of the health score is in the green area as defined in the health score settings
        - **String**:
            - Available for all textual default and custom attributes and has the following possible `filterType` values:
                - `is` - the value of the attribute is equal to the value provided in the `filterValue` field
                - `is_not` - the value of the attribute is different from the value provided in the `filterValue` field
                - `starts_with` - the value of the attribute starts with the value provided in `filterValue`
                - `ends_with` - the value of the attribute ends with the value provided in `filterValue`
                - `contains` - the value of the attribute contains the value provided in `filterValue`
                - `does_not_contain` - the value of the attribute does not contain the value provided in `filterValue`
                - `is_unknown` - the attribute/metric does not exist on the entity. The `filterValue` can be sent as either NULL or empty string
                - `any_value` - the attribute/metric exists on the entity and has any value. The `filterValue` can be sent as either NULL or empty string
            - Should also be used when the `fieldName` is `owners_csm` or `owners_account` (when filtering by Company CSM or Company Account Manager), but then the possible `filterType` values are:
                - `is` - in this particular case the `filterValue` should contain the Custify User ID of the CSM / Account Manager
                - `is_unknown` - means that the company does not have a CSM / Account Manager
        - **User**:
            - Available for attributes of type `User` (created using Event-attribute editor) and has the following possible `filterType` values:
                - `is` - the value of the attribute is equal to the value provided in the `filterValue` field and should contain the Custify User ID of the user
                - `is_unknown` - the attribute does not exist on the entity. The `filterValue` can be sent as either NULL or empty string
        - **Date**:
            - Available for all date default and custom attributes and has the following possible values for `filterType`:
                - `more_than` - means that the value of the attribute is more than X (where X is the value provided in `filterValue` - which is a Number) days ago
                - `exactly` - means that the value of the attribute is exactly X (where X is the value provided in `filterValue` - which is a Number) days ago
                - `less_than` - means that the value of the attribute is less than X (where X is the value provided in `filterValue` - which is a Number) days ago
                - `after` - means that the value of the attribute is after the date X (where X is the value provided in `filterValue` in the `YYYY-MM-DD` format)
                - `on`  - means that the value of the attribute is on the date X (where X is the value provided in `filterValue` in the `YYYY-MM-DD` format)
                - `before`  - means that the value of the attribute is before the date X (where X is the value provided in `filterValue` in the `YYYY-MM-DD` format)
                - `between`  - means that the value of the attribute is between the dates X and Y (where X and Y are the value provided in `filterValue` as an array `[X,Y]` each in the `YYYY-MM-DD` format)
        - **Boolean**:
            - Available for all boolean default and custom attributes and has the following possible values for `filterType`. Also, for Boolean fields the `filterValue` should always be empty string or NULL:
                - `true` - the value of the attribute is TRUE
                - `false` - the value of the attribute is FALSE
                - `is_unknown` - the attribute does not exist on the entity
                - `any_value` - the attribute exists on the entity and has any value
        - **Tag**:
            - This is the `fieldType` that must be used when filtering for the `tags` field and the following options for `filterType` are available
                - `is_in` - the `filterValue` must be the Custify ID of a tag and will return entities that have that tag applied
                - `is_not_in` - the `filterValue` must be the Custify ID of a tag and will return entities that do not have that tag applied
                - `is_unknown` - the `filterValue` should be either NULL or an empty string and will return entities that have no tags applied to them
        - **Company**:
            - This is the `fieldType` that must be used when filtering on `People` to retrieve people that are part of the specified company. The following options for `filterType` are available
                - `is_in` - the `filterValue` must be the Custify ID of a company and will return entities that match the applied filter
                - `is_unknown` - the `filterValue` should be either NULL or an empty string and will return entities that match the applied filter
        
        Filtering for `Parent companies` can be done using the following values for the fields:
        - `fieldName` should be `parent_companies`
        - `fieldType` should be `String`
        - `filterType` should have one of the options:
            - `is_descendant` - will return entities that are descendants (children, grand-children, etc...) of the company set in the `filterValue` field
            - `is_in` - will return entities that are children of the company set in the `filterValue` field
        - `filterValue` should be the Custify internal ID of the company for which the filtering values is applied.
        ### Filtering properties
        If you want to apply filters to the response from `/company/all` endpoint, you would need to send the `properties` query parameter as an URL-encoded array of fields to be returned.
        Some default properties are available for all entities: `id`, `name`, `created_at` and `updated_at`.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax200"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        },
        {
          $ref: "#/components/parameters/filteringParam"
        },
        {
          $ref: "#/components/parameters/includeSegmentsParam"
        },
        {
          $ref: "#/components/parameters/filteringProperties"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/company/all?itemsPerPage=10&page=7' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Company" ]
  "/company/people/{id}":
    get:
      summary: List Company People
      description: |
        The people belonging to a company can be listed by sending a GET request to https://api.custify.com/company/people/{id}, where {id} is the Custify internal ID of the company.
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          description: Param ID is missing or invalid
        '500':
          description: Some other error occurred
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/company/people/5b9f95d838ab5e09b8ed66cb' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      tags: [ "Company" ]
  "/note/{id}":
    post:
      summary: Create or update a note
      description: |
        You can create a new note or update an existing one by sending a POST request to [https://api.custify.com/note/{id}](https://api.custify.com/note/{id}), where {id} is the value of the Custify internal `id` of the note.
      parameters: [
        {
          $ref: "#/components/parameters/resourceIdOptional"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/note' \\\n
                                -X POST \\\n
                                -H 'Authorization: Bearer <Your access token>' \\\n
                                -H 'Accept: application/json' \\\n
                                -H 'Content-Type: application/json' -d ' \n{\n  \"text\": \"First note\",\n  \"entity\": \"5ed60ea90494f32ff3959079\",\n  \"entityModel\": \"Company\",\n  \"sticky\": true\n}'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Note"
        description: Note request object
        required: true
      tags: [ "Note" ]
  "/note/{entityId}":
    get:
      summary: List notes
      description: |
        You can fetch a list of notes. The list, by default, is sorted by `sticky` field when retrieving notes for just one entity and by `created_at` field when retrieving all notes. Also, by default, the order is `descending`, with the most recent notes first.
        You can request notes for a specific entity by sending a GET request to [https://api.custify.com/note/{entityId}](https://api.custify.com/note/{entityId}), where {entityId} is Custify internal `id`.
        ### Filtering notes
        If you want to apply filters to this endpoint, you would need to send the `filters` query parameter as an URL-encoded array of objects as follows:
        ```json
        [
          {
            field: "createdByEntity", //the field to filter by
            values: ['629dfbc3e827ed3cd0de1a53',…] //the values
          },
          ...
        ]
        ```
        The logic applied to filtering is `OR` between different values for the same field and `AND` between different fields, for example:
        ```
        (createdByEntity='value1' OR createdByEntity='value2') AND (tags='value3' OR tags='value4')
        ```

        The following fields can be filtered (including what can be sent in the values array):
          - `createdByEntity` - filters notes by who/what they were created by. The allowed values are `api`, `playbook_{id}`, `user_{id}`, `integration_{id}` where `{id}` is the Custify ID of the entity (for playbook and user) 
        or the name of the integration (like `hubspot`, `close`) that have created the note
          - `tags` - filters notes by tags, the values being Custify IDs of Tags
          - `mentioning` - filters notes by users mentioned in them, the values being Custify IDs of users
        
        Extra filtering can be archived by using the `searchTerm` query parameter and should be a string. This will filter notes by the text they contain or by the external ID if the note came from a integration.
      parameters: [
        {
          $ref: "#/components/parameters/limitParam"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortParam"
        },
        {
          $ref: "#/components/parameters/orderParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/note{/entityId}?itemsPerPage=10&page=7' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Note" ]
  "/tag/{id}":
    post:
      summary: Create or update a tag
      description: |
        You can create a new tag or update an existing one by sending a POST request to [https://api.custify.com/tag/{id}](https://api.custify.com/tag/{id}), where {id} is the value of the Custify internal `id` of the tag.
      parameters: [
        {
          $ref: "#/components/parameters/resourceIdOptional"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/tag' \\\n
                                -X POST \\\n
                                -H 'Authorization: Bearer <Your access token>' \\\n
                                -H 'Accept: application/json' \\\n
                                -H 'Content-Type: application/json' -d ' \n{\n  \"name\": \"First tag\",\n  \"description\": \"This is the first tag\"\n}'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Tag"
        description: Tag request object
        required: true
      tags: [ "Tag" ]
    get:
      summary: List tags
      description: |
        You can fetch a list of tags. The list, by default, is sorted by `position` field and in `ascending` order. The list can also be filtered by sending in the query params the `category` of the tag you want to filter.
      parameters: [
        {
          $ref: "#/components/parameters/limitParam"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortParam"
        },
        {
          $ref: "#/components/parameters/orderParam"
        },
        {
          $ref: "#/components/parameters/categoryParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/tag{/id}?itemsPerPage=10&page=7' \\\n
                          -X GET \\\n
                          -H 'Authorization: Bearer <Your access token>' \\\n
                          -H 'Accept: application/json' \\\n
                          -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Tag" ]
  "/tag/id":
    delete:
      summary: Delete a tag
      description: |
        Tags can be deleted by sending a DELETE request to the entry's URL using the Custify *id* field as part of the path
        - `https://api.custify.com/tag/id`

        Note that this function permanently deletes the corresponding tag set on people.
      parameters: [
        {
          $ref: "#/components/parameters/resourceId"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/tag/5ea214c0789e2733b73d8e27' \\\n
                    -X DELETE \\\n
                    -H 'Authorization: Bearer <Your access token>' \\\n
                    -H 'Accept: application/json' \\\n
                    -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (invalid request syntax)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      tags: [ "Tag" ]
  "/tag/entity":
    patch:
      summary: Add/remove tags to entities
      description: |
        Tags can be added/removed to/from multiple entities of the same category by sending a PATCH request to the URL `https://api.custify.com/tag/entity`.
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/tag/entity' \\\n
                    -X PATCH \\\n
                    -H 'Authorization: Bearer <Your access token>' \\\n
                    -H 'Accept: application/json' \\\n
                    -H 'Content-Type: application/json' -d ' \n{\n  \"ids\": [\"634523fe5418640067e1031a\",\"6322e4cf0d47b2d3eb97811d\"],\n  \"type\": \"add\",\n  \"category\": \"people\",\n  \"tag\": \"6345240b5418640067e1033a\"\n}'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (invalid request syntax)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TagEntity"
        description: Add/remove tags to entities request object
        required: true
      tags: [ "Tag" ]
  "/custom_data/{entityModel}/{entity}":
    post:
      summary: Add or update a custom data object
      description: |
        You can add new custom data objects or update existing ones by sending a POST request to [https://api.custify.com/custom_data/{entityModel}/{entity}](https://api.custify.com/custom_data/{entityModel}/{entity}), where {entityModel} is 'companies' or 'people', depending on the type of entity you are adding the custom data object to and {entity} is the Custify internal `id` of the Company or People.
        Alternatively, you can add new custom data objects or update existing ones by sending a POST request to:
        - [https://api.custify.com/custom_data/{entityModel}?company_id=123](https://api.custify.com/custom_data/{entityModel}?company_id=123) for `{entityModel}=companies` or
        - [https://api.custify.com/custom_data/{entityModel}?user_id=123](https://api.custify.com/custom_data/{entityModel}?user_id=123) for `{entityModel}=people`

        where `company_id` or `user_id` is the entity ID from your own system.

        Note that the combination of `data_type` and `data_id` represents an unique index and triggers the creation or updating of a custom data object.

        You can also send bulk custom data objects for the current entity by sending an array of the Custom data request objects.
      parameters: [
        {
          $ref: "#/components/parameters/entityModel"
        },
        {
          $ref: "#/components/parameters/entityNotRequired"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/custom_data/:entityModel/:entity' \\\n
                                    -X POST \\\n
                                    -H 'Authorization: Bearer <Your access token>' \\\n
                                    -H 'Accept: application/json' \\\n
                                    -H 'Content-Type: application/json' -d ' \n{\n  \"data_type\": \"invoice\",\n  \"data_id\": \"INV_001\",\n  \"data\": {}\n}'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CustomData"
        description: Custom data request object
        required: true
      tags: [ "CustomData" ]
    get:
      summary: List custom data objects
      description: |
        You can list custom data objects by sending a GET request to [https://api.custify.com/custom_data/{entityModel}/{entity}](https://api.custify.com/custom_data/{entityModel}/{entity}), where {entityModel} is 'companies' or 'people', depending on the type of entity you are adding the custom data object to and {entity} is the Custify internal `id` of the Company or People.
        Alternatively, you can list custom data objects by sending a GET request to:
        - [https://api.custify.com/custom_data/{entityModel}?company_id=123](https://api.custify.com/custom_data/{entityModel}?company_id=123) for `{entityModel}=companies` or
        - [https://api.custify.com/custom_data/{entityModel}?user_id=123](https://api.custify.com/custom_data/{entityModel}?user_id=123) for `{entityModel}=people`
        
        where `company_id` or `user_id` is the entity ID from your own system. You can also filter the custom data objects by sending the query params {data_type} and/or {data_id} (ex. [https://api.custify.com/custom_data/{entityModel}/{entity}](https://api.custify.com/custom_data/{entityModel}/{entity}?data_type=invoice&data_id=invoice1]).
      parameters: [
        {
          $ref: "#/components/parameters/entityModel"
        },
        {
          $ref: "#/components/parameters/entityNotRequired"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/custom_data/:entityModel/:entity' \\\n
                                    -X GET \\\n
                                    -H 'Authorization: Bearer <Your access token>' \\\n
                                    -H 'Accept: application/json' \\\n'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data_type_1:
                    description: An array of objects with the details of the custom data
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomDataListing'
                  data_type_2:
                    description: An array of objects with the details of the custom data
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomDataListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "CustomData" ]
    delete:
      summary: Delete a custom data object
      description: |
        You can delete one or more custom data objects by sending a DELETE request to:
        - [https://api.custify.com/custom_data/{entityModel}/{entity}](https://api.custify.com/custom_data/{entityModel}/{entity}), where {entityModel} is 'companies' or 'people', depending on the type of entity you are adding the custom data object to and {entity} is the Custify internal `id` of the Company or People or
        - [https://api.custify.com/custom_data/{entityModel}](https://api.custify.com/custom_data/{entityModel}), where {entityModel} is 'companies' or 'people', depending on the type of entity you are adding the custom data object to

        You can also enhance the request by sending in the query params {data_type} and/or {data_id}. If you use the second request type you must send as a query param also {company_id} or {user_id} (depending on the type of entity of custom data object) where `company_id` or `user_id` is the entity ID from your own system.
      parameters: [
        {
          $ref: "#/components/parameters/entityModel"
        },
        {
          $ref: "#/components/parameters/entityNotRequired"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/custom_data/:entityModel/:entity' \\\n
                                      -X DELETE \\\n
                                      -H 'Authorization: Bearer <Your access token>' \\\n
                                      -H 'Accept: application/json'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (invalid request syntax)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "CustomData" ]
  "/nps_score/{entity}":
    post:
      summary: Assign a nps score to a people
      description: |
        You can assign a nps score to a people by sending a POST request to [https://api.custify.com/nps_score/{entity}](https://api.custify.com/nps_score/{entity}), where {entity} is the Custify internal `id` of the People.
        Alternatively, you can assign a nps score to a people by sending a POST request to:
        - [https://api.custify.com/nps_score?email=john.doe@custify.com](https://api.custify.com/nps_score?email=john.doe@custify.com) or
        - [https://api.custify.com/nps_score?user_id=123](https://api.custify.com/nps_score?user_id=123) where `user_id` is the ID from your system.
        You can also assign the nps score to a survey by sending a POST request to [https://api.custify.com/nps_score?{surveyId=xyz}](https://api.custify.com/nps_score?{surveyId=xyz}), where {surveyId} is the Custify internal `id` of the Survey.

        In the body of the request you can send the NPS score (`score`), a comment (`comment`) and the date of the NPS score (`submittedAt`). Only the field `score` is required. If you don't provide the `submittedAt` field it will be saved the current UTC time.
        If the people for which you're sending the NPS score already has saved a NPS score, it will be kept the newest one based on the `submittedAt` date field.
        If the people you're assigning the NPS score is linked to a company then also the company gets assigned a NPS score which is calculated as the arithmetic mean (rounded to the nearest integer) of all people's NPS scores that are linked to the company.
      parameters: [
        {
          $ref: "#/components/parameters/entity"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/nps_score/:entity' \\\n
                                    -X POST \\\n
                                    -H 'Authorization: Bearer <Your access token>' \\\n
                                    -H 'Accept: application/json' \\\n
                                    -H 'Content-Type: application/json' -d ' \n{\n  \"score\": 9,\n  \"comment\": \"Almost perfect\",\n  \"submittedAt\": \"2021-04-10T12:00:00.000Z\"\n}'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/NPSScore"
        description: NPS score request object
        required: true
      tags: [ "NPSScore" ]
  "/csat_score/{entity}":
    post:
      summary: Assign a CSAT score to a people
      description: |
        You can assign a CSAT score to a people by sending a POST request to [https://api.custify.com/csat_score/{entity}](https://api.custify.com/csat_score/{entity}), where {entity} is the Custify internal `id` of the People.
        Alternatively, you can assign a CSAT score to a people by sending a POST request to:
        - [https://api.custify.com/csat_score?email=john.doe@custify.com](https://api.custify.com/csat_score?email=john.doe@custify.com) or
        - [https://api.custify.com/csat_score?user_id=123](https://api.custify.com/csat_score?user_id=123) where `user_id` is the ID from your system.
        You can also assign the CSAT score to a survey by sending a POST request to [https://api.custify.com/csat_score?{surveyId=xyz}](https://api.custify.com/csat_score?{surveyId=xyz}), where {surveyId} is the Custify internal `id` of the Survey.

        In the body of the request you can send the CSAT score (`score`), a comment (`comment`) and the date of the CSAT score (`submittedAt`). Only the field `score` is required. If you don't provide the `submittedAt` field it will be saved the current UTC time.
        If the people for which you're sending the CSAT score already has saved a CSAT score, it will be kept the newest one based on the `submittedAt` date field.
        If the people you're assigning the CSAT score is linked to a company then also the company gets assigned a CSAT score which is calculated as the arithmetic mean (rounded to the nearest integer) of all people's CSAT scores that are linked to the company.
      parameters: [
        {
          $ref: "#/components/parameters/entity"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/csat_score/:entity' \\\n
                                    -X POST \\\n
                                    -H 'Authorization: Bearer <Your access token>' \\\n
                                    -H 'Accept: application/json' \\\n
                                    -H 'Content-Type: application/json' -d ' \n{\n  \"score\": 5,\n  \"comment\": \"Very satisfied\",\n  \"submittedAt\": \"2021-04-10T12:00:00.000Z\"\n}'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/CSATScore"
        description: CSAT score request object
        required: true
      tags: [ "CSATScore" ]
  /batch:
    post:
      summary: Send batch requests
      description: |
        You can send batch requests for creating/updating people or companies, for creating events or custom data. The requests can be processes synchronous or asynchronous based on the value sent in the request. The default processing is asynchronous.
        For asynchronous jobs you can have a return job id which can be used to retrieve the status of the processing. If synchronous is set to true then the maximum number of jobs you can provide is 3. If synchronous is set to false you can provide maximum 100 jobs.
        The jobs can be mixed (for people, companies, events or custom data). The return job id is kept for 6 hours after the last job in the batch is processed. The payload of the job depends of the type of job and should contain data in the same format as when creating/updating people, companies or events.
        For custom data the payload should look like:
        ```json
        {
          "type": "custom-data",
          "payload": {
            "entity": "65240f85e2a675bd3090a3d3",
            "entityModel": "Company",
            "data_type": "invoice",
            "data_id": "INV_003",
            "data": {
                "amount": 175,
                "invoiced_at": "2023-02-02T00:00:00Z",
                "is_paid": false,
                "product_name": "bronze_plan"
            }
          }
        }
        ```
        Alternatively, if you don't know the Custify entity ID you can send the `company_id` or `user_id` from your system by replacing field `entity` in the payload.
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/batch' \\\n
                                    -X POST \\\n
                                    -H 'Authorization: Bearer <Your access token>' \\\n
                                    -H 'Accept: application/json' \\\n
                                    -H 'Content-Type: application/json' -d ' \n{\n  \"jobs\": [\n    {\n      \"type\": \"people\",\n      \"payload\": {\n        \"name\": \"John Doe\",\n        \"user_id\": \"batch_1\",\n        \"email\": \"john.doe@outlook.com\"\n      }\n    }\n  ],\n  \"synchronous\": false,\n  \"returnJobId\": \"35757461-c988-5508-9f80-68bd45a99bf9\"\n}'"
      responses:
        '202':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Batch"
        description: Batch request object
        required: true
      tags: [ "Batch" ]
  "/batch/id":
    get:
      summary: Get batch job status
      description: |
        Get status and results of the batch processing by provinding a 'returnJobId'.
      parameters: [
        {
          $ref: "#/components/parameters/batchJobId"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/batch/id\\\n
                          -X GET \\\n
                          -H 'Authorization: Bearer <Your access token>' \\\n
                          -H 'Accept: application/json' \\\n
                          -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Batch" ]
  /ticket:
    post:
      summary: Create a new ticket
      description: |
        Create a new ticket on Companies or People.
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Ticket"
        description: Ticket request object
        required: true
      tags: [ "Tickets" ]
    get:
      summary: List all tickets
      description: |
        You can fetch a list of all tickets across all companies and people. The list, by default, is sorted by the `openedAt` field and in `descending` order, with the most recent tickets first.
        
        ### Filtering tickets
        If you want to apply filters to the `/ticket` endpoint, you would need to send the `filters` query parameter as an URL-encoded array of objects. The filtering logic is similar to other entities:
        ```json
        [
            {
                "field": "ticketStatus",
                "values": ["open", "pending"]
            },
            {
                "field": "priority",
                "values": ["high"]
            }
        ]
        ```
        The logic applied to filtering is `OR` between different values for the same field and `AND` between different fields, for example:
        ```
        (ticketStatus='open' OR ticketStatus='pending') AND (priority='high')
        ```
        
        ### Available filter fields
        - `ticketStatus` - filters tickets by their status
        - `priority` - filters tickets by priority level
        - `assignedToName` - filters tickets by assigned user name
        - `provider` - filters tickets by provider/source system
        - `tags` - filters tickets by tag IDs (array of tag IDs)
        - `csm` - filters tickets by CSM email addresses
        - `segments` - filters tickets by company segments (Custify internal segment IDs)
        
        ### Search
        You can search tickets using the `searchTerm` query parameter. The search will look through ticket title, description, and other text fields.
      parameters:
        - $ref: "#/components/parameters/itemsPerPageMax200"
        - $ref: "#/components/parameters/pageParam"
        - name: sort
          in: query
          description: Field to sort by
          schema:
            type: string
            default: openedAt
            example: openedAt
        - name: order
          in: query
          description: Sort order (asc or desc)
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
        - name: filters
          in: query
          description: The resource items filters
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ListingTicketFilter'
        - name: searchTerm
          in: query
          description: Search term to filter tickets
          schema:
            type: string
            example: "login issue"
        - name: externalId
          in: query
          description: Filter tickets by their external ID (e.g. the ticket ID from your helpdesk system like Zendesk, Freshdesk, etc.)
          schema:
            type: string
            example: "TICKET-123"
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/ticket?itemsPerPage=20&page=1&sort=openedAt&order=desc' \\\n
                -X GET \\\n
                -H 'Authorization: Bearer <Your access token>' \\\n
                -H 'Accept: application/json' \\\n
                -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of tickets matching the query
                    example: 150
                  tickets:
                    type: array
                    description: Array of ticket objects
                    items:
                      $ref: '#/components/schemas/TicketListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Tickets" ]
  "/ticket/ticketExternalId":
    put:
      summary: Update an existing ticket
      description: |
        Update an existing ticket based on the externalId for the ticket. Works as a patch, only provided fields are saved. If `replies` is sent, it overwrites the existing array of replies.
      parameters: [
        {
          $ref: "#/components/parameters/ticketExternalId"
        }
      ]
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Tickets" ]
    delete:
      summary: Delete an existing ticket
      description: |
        Delete an existing ticket based on the externalId for the ticket
      parameters: [
        {
          $ref: "#/components/parameters/ticketExternalId"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/ticket/ticketExternalId\\\n
                          -X DELETE \\\n
                          -H 'Authorization: Bearer <Your access token>' \\\n
                          -H 'Accept: application/json' \\\n
                          -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (invalid request syntax)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      tags: [ "Tickets" ]
  "/ticket/ticketExternalId/reply":
    post:
      summary: Add a reply to an existing ticket
      description: |
        Add a new reply to an existing ticket based on the externalId. This endpoint accepts one single object like the one in the replies array in the ticket structure.
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/ticket/ticketExternalId/reply' \\\n
                                    -X POST \\\n
                                    -H 'Authorization: Bearer <Your access token>' \\\n
                                    -H 'Accept: application/json' \\\n
                                    -H 'Content-Type: application/json' -d ' \n{\n  \"jobs\": [\n    {\n      \"type\": \"people\",\n      \"payload\": {\n        \"name\": \"John Doe\",\n        \"user_id\": \"batch_1\",\n        \"email\": \"john.doe@outlook.com\"\n      }\n    }\n  ],\n  \"synchronous\": false,\n  \"returnJobId\": \"35757461-c988-5508-9f80-68bd45a99bf9\"\n}'"
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TicketReply"
        description: Ticket reply request object
        required: true
      tags: [ "Tickets" ]
  "/ticket/{entity}":
    get:
      summary: List tickets for a specific company or person
      description: |
        You can fetch a list of tickets associated with a specific company or person by sending a GET request to [https://api.custify.com/ticket/{entity}](https://api.custify.com/ticket/{entity}), where {entity} is the Custify internal ID of either a company or a person.
        
        The endpoint automatically detects whether the provided ID belongs to a company or a person and returns all tickets associated with that entity. The list, by default, is sorted by the `openedAt` field and in `descending` order, with the most recent tickets first.
        
        ### Filtering tickets
        If you want to apply filters to the `/ticket/{entity}` endpoint, you would need to send the `filters` query parameter as an URL-encoded array of objects. The filtering logic is similar to other entities:
        ```json
        [
            {
                "field": "ticketStatus",
                "values": ["open", "pending"]
            },
            {
                "field": "priority",
                "values": ["high"]
            }
        ]
        ```
        
        ### Search
        You can search tickets using the `searchTerm` query parameter. The search will look through ticket title, description, and other text fields.
      parameters:
        - name: entity
          in: path
          required: true
          description: Custify internal ID of the company or person
          schema:
            type: string
            example: "5ea93252e0263c08145d6944"
        - $ref: "#/components/parameters/itemsPerPageMax200"
        - $ref: "#/components/parameters/pageParam"
        - name: sort
          in: query
          description: Field to sort by
          schema:
            type: string
            default: openedAt
            example: openedAt
        - name: order
          in: query
          description: Sort order (asc or desc)
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
        - name: filters
          in: query
          description: The resource items filters
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ListingTicketFilter'
        - name: searchTerm
          in: query
          description: Search term to filter tickets
          schema:
            type: string
            example: "login issue"
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/ticket/5ea93252e0263c08145d6944?itemsPerPage=20&page=1&sort=openedAt&order=desc' \\\n
                -X GET \\\n
                -H 'Authorization: Bearer <Your access token>' \\\n
                -H 'Accept: application/json' \\\n
                -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of tickets matching the query
                    example: 25
                  tickets:
                    type: array
                    description: Array of ticket objects
                    items:
                      $ref: '#/components/schemas/TicketListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          description: Entity not found
        '500':
          description: Some other error occurred
      tags: [ "Tickets" ]
  /task:
    post:
      summary: Create a new task
      description: |
        Create a new task on Companies.
        ### Dynamic data in tasks
        The task `description` accepts dynamic data fields that are being automatically populated with data from either the Company or the Person that it is being assigned to.

        In order use dynamic data, it should be sent as follows: `{company:name}` or `{people:name}`.

        In order to use custom attributes, metrics or health scores in the dynamic data, they should be sent in a dot-notation format, as follows:
        - `{company:custom_attributes.account_owner}`
        - `{company:metrics.people_count}`
        - `{company:metrics.calculated_metrics.calculatedMetricID}`
        - `{company:metrics.health_scores.healthScoreID}`
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Task"
        description: Task request object
        required: true
      tags: [ "Tasks" ]
    get:
      summary: List the tasks
      description: |
        List the tasks.
        ### Filtering tasks
        If you want to apply filters to the LIST endpoint, you would need to send the filters query parameter as an URL-encoded array of objects as follows:
        ```json
        [
            {
                field: "createdBy", //the field to filter by
                values: ['629dfbc3e827ed3cd0de1a53',…] //the values
            },
            ...
        ]
        ```
        The logic applied to filtering is `OR` between different values for the same field and `AND` between different fields, for example:
        ```
        (createdBy='value1' OR createdBy='value2') AND (status='value3' OR status='value4')
        ```

        The following fields can be filtered (including what can be sent in the values array):
        - `createdBy` - filters tasks by who/what they were created by. The allowed values are Custify IDs of Users, Playbooks and Lifecycles that have created the task
        - `company` - filters tasks by which company/companies they are assigned to. The values are Custify IDs for Companies
        - `assignedTo` - filters tasks by which User they are assigned to. The values are Custify IDs of Users or emails
        - `tags` - filters tasks by tags, the values being Custify IDs of Tags
        - `status` - filters tasks by status, the possible values being: `open`, `done`, `not relevant`, `snoozed` and `overdue`
        
        Extra filtering can be archived by using the `searchTerm` query parameter and should be a string. This will filter tasks by the name of the task or the description of the task.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        },
        {
          $ref: "#/components/parameters/filteringTaskParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/task?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of tasks
                    type: integer
                    example: 1
                  tasks:
                    description: An array of objects with the details of the tasks
                    type: array
                    items:
                      $ref: '#/components/schemas/TaskListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Tasks" ]
  "/task/filtersAvailableValues":
    get:
      summary: List available filter values
      description: List available filters values for tasks.
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/task/filtersAvailableValues' \\\n
                            -X GET \\\n
                            -H 'Authorization: Bearer <Your access token>' \\\n
                            -H 'Accept: application/json' \\\n
                            -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  company:
                    description: Array of objects with name of the company and the Custify ID
                    type: array
                    items:
                      $ref: '#/components/schemas/TaskCompanyFilter'
                  assignedTo:
                    description: An array of objects with id and the name of the user
                    type: array
                    items:
                      $ref: '#/components/schemas/TaskAssignedtoFilter'
                  createdBy:
                    description: An array of objects with id and the name of the user/lifecycle/playbook
                    type: array
                    items:
                      $ref: '#/components/schemas/TaskCreatedbyFilter'
                  tags:
                    description: An array of objects with id of the tags
                    type: array
                    items:
                      $ref: '#/components/schemas/TaskTagsFilter'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Tasks" ]
  "/task/{id}":
    get:
      summary: List a task details
      description: List a task details using Custify ID of the task or using the `externalId` field (as a query param). When trying to list a task details using the `externalId` make a `GET` request to the endpoint `/task?externalId=abc` where `abc` is the `externalId` value.
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/task/5b9f95d838ab5e09b8ed66cb' \\\n
                            -X GET \\\n
                            -H 'Authorization: Bearer <Your access token>' \\\n
                            -H 'Accept: application/json' \\\n
                            -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of tasks
                    type: integer
                    example: 1
                  tasks:
                    description: An array of objects with the details of the tasks
                    type: array
                    items:
                      $ref: '#/components/schemas/TaskListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Tasks" ]
    put:
      summary: Update an existing task
      description: Update an existing task. You can send only the data that changes by providing the Custify internal ID `_id` of the existing task.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TaskUpdate"
        description: Task update request object
        required: true
      tags: [ "Tasks" ]
  "/comment/{entityModel}/{entity}":
    post:
      summary: Create or update a comment
      description: |
        You can create a new comment or update an existing one by sending a POST request to [https://api.custify.com/comment/{entityModel}/{entity}](https://api.custify.com/comment/{entityModel}/{entity}), , where {entityModel} is 'Note' or 'Task', depending on the type of entity you are adding the comment to and {entity} is the Custify internal `id` of the Note or Task.
      parameters: [
        {
          $ref: "#/components/parameters/entityModelComment"
        },
        {
          $ref: "#/components/parameters/entity"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/comment/:entityModel/:entity' \\\n
                                    -X POST \\\n
                                    -H 'Authorization: Bearer <Your access token>' \\\n
                                    -H 'Accept: application/json' \\\n
                                    -H 'Content-Type: application/json' -d ' \n{\n  \"text\": \"First comment\"\n}'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommentListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Comment"
        description: Comment request object
        required: true
      tags: [ "Comments" ]
    get:
      summary: List the comments
      description: |
        List the comments.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortParam"
        },
        {
          $ref: "#/components/parameters/orderParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/comment/:entityModel/:entity?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of comments
                    type: integer
                    example: 15
                  comments:
                    description: An array of objects with the details of the comments
                    type: array
                    items:
                      $ref: '#/components/schemas/CommentListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Comments" ]
  "/financial/deal/{entity}":
    post:
      summary: Create or update a financial deal
      description: |
        You can create a new financial deal or update an existing one by sending a POST request to [https://api.custify.com/financial/deal/{entity}](https://api.custify.com/financial/deal/{entity}), where {entity} is the Custify internal `id` of the Financial Deal.
        Alternatively, you can create/update financial deals by sending a POST request to [https://api.custify.com/financial/deal](https://api.custify.com/financial/deal) that has in the body the field `externalId`, where `externalId` is your internal ID of the deal.
      parameters: [
        {
          $ref: "#/components/parameters/entityFinancial"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/financial/deal' \\\n
                                    -X POST \\\n
                                    -H 'Authorization: Bearer <Your access token>' \\\n
                                    -H 'Accept: application/json' \\\n
                                    -H 'Content-Type: application/json' -d ' \n{\n  \"externalId\": \"deal01\"\n  \"company_id\": \"123\"\n  \"status\": \"pending\"\n}'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialDealListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FinancialDeal"
        description: Financial Deal request object
        required: true
      tags: [ "Financial Deals" ]
    get:
      summary: List the financial deals
      description: |
        List the financial deals. When the result of the request is only one financial deal the response will be directly the financial deal object.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortParam"
        },
        {
          $ref: "#/components/parameters/orderParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/financial/deal/:entity?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of financial deals
                    type: integer
                    example: 15
                  deals:
                    description: An array of objects with the details of the financial deals
                    type: array
                    items:
                      $ref: '#/components/schemas/FinancialDealListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Financial Deals" ]
    delete:
      summary: Delete an existing financial deal
      description: |
        Delete an existing financial deal based on the `externalId` for the financial deal (in the query params) or the `entity` in the params of the request.
      parameters: [
        {
          $ref: "#/components/parameters/financialExternalId"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/financial/deal?externalId=abc\\\n
                          -X DELETE \\\n
                          -H 'Authorization: Bearer <Your access token>' \\\n
                          -H 'Accept: application/json' \\\n
                          -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (invalid request syntax)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      tags: [ "Financial Deals" ]
  "/financial/invoice/{entity}":
    post:
      summary: Create or update a financial invoice
      description: |
        You can create a new financial invoice or update an existing one by sending a POST request to [https://api.custify.com/financial/invoice/{entity}](https://api.custify.com/financial/invoice/{entity}), where {entity} is the Custify internal `id` of the Financial Invoice.
        Alternatively, you can create/update financial invoices by sending a POST request to [https://api.custify.com/financial/invoice](https://api.custify.com/financial/invoice) that has in the body the field `externalId`, where `externalId` is your internal ID of the invoice.
      parameters: [
        {
          $ref: "#/components/parameters/entityFinancial"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/financial/invoice' \\\n
                                    -X POST \\\n
                                    -H 'Authorization: Bearer <Your access token>' \\\n
                                    -H 'Accept: application/json' \\\n
                                    -H 'Content-Type: application/json' -d ' \n{\n  \"externalId\": \"invoice01\"\n  \"company_id\": \"123\"\n  \"status\": \"unpaid\"\n  \"total\": 199\n}'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialInvoiceListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FinancialInvoice"
        description: Financial Invoice request object
        required: true
      tags: [ "Financial Invoices" ]
    get:
      summary: List the financial invoices
      description: |
        List the financial invoices. When the result of the request is only one financial invoice the response will be directly the financial invoice object.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortParam"
        },
        {
          $ref: "#/components/parameters/orderParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/financial/invoice/:entity?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of financial invoices
                    type: integer
                    example: 15
                  invoices:
                    description: An array of objects with the details of the financial invoices
                    type: array
                    items:
                      $ref: '#/components/schemas/FinancialInvoiceListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Financial Invoices" ]
    delete:
      summary: Delete an existing financial invoice
      description: |
        Delete an existing financial invoice based on the `externalId` for the financial invoice (in the query params) or the `entity` in the params of the request.
      parameters: [
        {
          $ref: "#/components/parameters/financialExternalId"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/financial/invoice?externalId=abc\\\n
                          -X DELETE \\\n
                          -H 'Authorization: Bearer <Your access token>' \\\n
                          -H 'Accept: application/json' \\\n
                          -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (invalid request syntax)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      tags: [ "Financial Invoices" ]
  "/financial/subscription/{entity}":
    post:
      summary: Create or update a financial subscription
      description: |
        You can create a new financial subscription or update an existing one by sending a POST request to [https://api.custify.com/financial/subscription/{entity}](https://api.custify.com/financial/subscription/{entity}), where {entity} is the Custify internal `id` of the Financial Subscription.
        Alternatively, you can create/update financial subscriptions by sending a POST request to [https://api.custify.com/financial/subscription](https://api.custify.com/financial/subscription) that has in the body the field `externalId`, where `externalId` is your internal ID of the subscription.
      parameters: [
        {
          $ref: "#/components/parameters/entityFinancial"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/financial/subscription' \\\n
                                    -X POST \\\n
                                    -H 'Authorization: Bearer <Your access token>' \\\n
                                    -H 'Accept: application/json' \\\n
                                    -H 'Content-Type: application/json' -d ' \n{\n  \"externalId\": \"subscription01\"\n  \"company_id\": \"123\"\n  \"mrr\": 199\n}'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialSubscriptionListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FinancialSubscription"
        description: Financial Subscription request object
        required: true
      tags: [ "Financial Subscriptions" ]
    get:
      summary: List the financial subscriptions
      description: |
        List the financial subscriptions. When the result of the request is only one financial subscription the response will be directly the financial subscription object.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortParam"
        },
        {
          $ref: "#/components/parameters/orderParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/financial/subscription/:entity?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of financial subscriptions
                    type: integer
                    example: 15
                  subscriptions:
                    description: An array of objects with the details of the financial subscriptions
                    type: array
                    items:
                      $ref: '#/components/schemas/FinancialSubscriptionListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Financial Subscriptions" ]
    delete:
      summary: Delete an existing financial subscription
      description: |
        Delete an existing financial subscription based on the `externalId` for the financial subscription (in the query params) or the `entity` in the params of the request.
      parameters: [
        {
          $ref: "#/components/parameters/financialExternalId"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/financial/subscription?externalId=abc\\\n
                          -X DELETE \\\n
                          -H 'Authorization: Bearer <Your access token>' \\\n
                          -H 'Accept: application/json' \\\n
                          -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (invalid request syntax)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      tags: [ "Financial Subscriptions" ]
  "/file":
    post:
      summary: Upload a file
      description: |
        You can upload a file to a Company or a People by sending a POST request to [https://api.custify.com/file](https://api.custify.com/file). The request must have the `Content-Type` header set to `multipart/form-data`.
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileUploadListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '409':
          $ref: "#/components/responses/Conflict"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          multipart/form-data:
            schema:
              "$ref": "#/components/schemas/File"
        description: File request object
        required: true
      tags: [ "Files" ]
    get:
      summary: List files
      description: |
        You can list files for a Company or a People by sending a GET request to [https://api.custify.com/file](https://api.custify.com/file). You can send additional query params to filter or paginate results.
      parameters: [
        {
          $ref: "#/components/parameters/companyIdQuery"
        },
        {
          $ref: "#/components/parameters/peopleIdQuery"
        },
        {
          $ref: "#/components/parameters/searchKeyQuery"
        },
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        }
      ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FilesListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
      tags: [ "Files" ]
  "/file/unlink":
    post:
      summary: Unlink a file
      description: |
        You can unlink a file from a Company or a People by sending a POST request to [https://api.custify.com/file/unlink](https://api.custify.com/file/unlink).
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FileUnlink"
        description: File unlink request object
        required: true
      tags: [ "Files" ]
  "/file/:id/showInPortal":
    put:
      summary: Enable/disable file to be shown in the portal
      description: |
        Enable or disable a file to be shown in the portal by sending a PUT request to [https://api.custify.com/file/:id/showInPortal](https://api.custify.com/file/:id/showInPortal) where `:id` is the Custify internal ID of the file.
      responses:
        '200':
          description: Successful operation
        '401':
          $ref: "#/components/responses/AccessForbidden"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/FileShowInPortal"
        description: File enable/disable show in portal request object
        required: true
      tags: [ "Files" ]
  "/survey":
    get:
      summary: List surveys
      description: |
        You can list surveys. You can send additional query params to filter or paginate results.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        }
      ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveysListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
      tags: [ "Surveys" ]
  "/survey/{id}/responses":
    get:
      summary: Get survey responses
      description: |
        You can get the responses for a specific survey by sending a GET request to [https://api.custify.com/survey/{id}/responses](https://api.custify.com/survey/{id}/responses), where `{id}` is the Custify internal ID of the survey.

        The response includes the list of individual survey responses with the respondent's email, name, score, comment, response date and any extra question answers. Results are sorted by response date in descending order (most recent first).

        This endpoint is useful for exporting survey data per survey, allowing you to identify which survey a response belongs to (e.g., when you have multiple NPS surveys for different products).
      parameters: [
        {
          $ref: "#/components/parameters/resourceId"
        },
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/survey/5ea93252e0263c08145d6948/responses?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyResponsesResult'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          description: Survey not found
      tags: [ "Surveys" ]
  "/time-track":
    post:
      summary: Create a new time track
      description: |
        Create a new time track on Companies or People. When adding a time track for a Company, you need to provide the `company` field in the body of the request or the `company_id` in the query params. When adding a time track for a People, you need to provide the `people` field in the body of the request or the `user_id` pr `email` in the query params.
      parameters: [
        {
          $ref: "#/components/parameters/userParamRequired"
        },
        {
          $ref: "#/components/parameters/companyIdParam"
        },
        {
          $ref: "#/components/parameters/userIdParam"
        },
        {
          $ref: "#/components/parameters/emailParam"
        }
      ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeTrackListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TimeTrack"
        description: Time track request object
        required: true
      tags: [ "Time Tracking" ]
    put:
      summary: Update an exiting time track
      description: |
        Update an existing time track on Companies or People. When adding a time track for a Company, you need to provide the `company` field in the body of the request or the `company_id` in the query params. When adding a time track for a People, you need to provide the `people` field in the body of the request or the `user_id` pr `email` in the query params.
      parameters: [
        {
          $ref: "#/components/parameters/userParamRequired"
        },
        {
          $ref: "#/components/parameters/companyIdParam"
        },
        {
          $ref: "#/components/parameters/userIdParam"
        },
        {
          $ref: "#/components/parameters/emailParam"
        }
      ]
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeTrackListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/TimeTrack"
        description: Time track request object
        required: true
      tags: [ "Time Tracking" ]
    get:
      summary: List the time tracks
      description: |
        List the time tracks. You can send additional query params to filter or paginate results, like:
        - `company` (Custify company internal ID) or `company_id` (your internal company ID) - filters time tracks by which company/companies they are assigned to.
        - `people` (Custify people internal ID) or `user_id` (your internal user ID) or `email` - filters time tracks by which people they are assigned to.
        - `tags` - filters time tracks by tags, the values being Custify IDs of Tags.
        - `start_date` - filters time tracks by the start date of the time track.
        - `end_date` - filters time tracks by the end date of the time track.
        - `user` - filters time tracks by the user who created the time track. It can be the Custify internal ID of the user or the email of the user.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/time_track?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of time tracks
                    type: integer
                    example: 1
                  time_track:
                    description: An array of objects with the details of the time tracks
                    type: array
                    items:
                      $ref: '#/components/schemas/TimeTrackListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Time Tracking" ]
    delete:
      summary: Delete an existing time track
      description: |
        Delete an existing time track based on the Custify internal ID (in the query params).
      parameters: [
        {
          $ref: "#/components/parameters/resourceId"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/time_track/{:id}\\\n
                          -X DELETE \\\n
                          -H 'Authorization: Bearer <Your access token>' \\\n
                          -H 'Accept: application/json' \\\n
                          -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (invalid request syntax)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          $ref: "#/components/responses/NotFound"
        '500':
          description: Some other error occurred
      tags: [ "Time Tracking" ]
  "/calendar/meeting":
    post:
      summary: Create or update a meeting
      description: |
        Create or update a meeting by sending a `POST` request to [https://api.custify.com/calendar/meeting](https://api.custify.com/calendar/meeting).

        ### Entity association
        You must associate the meeting with at least one person or company using your external IDs:
        - `user_id` (your internal user ID) — resolves the person and automatically links their companies
        - `email` — alternative to `user_id` for person lookup
        - `company_id` (your internal company ID) — links the meeting directly to a company

        At least one of `user_id`, `email`, or `company_id` is required.

        ### Create vs Update
        - If `id` (Custify internal ID) is provided in the body, the matching meeting will be updated.
        - If `externalId` is provided, the meeting will be looked up by that ID and updated, or created if not found.
        - If neither is provided, a new meeting is always created.
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/calendar/meeting' \\\n
          -X POST \\\n
          -H 'Authorization: Bearer <Your access token>' \\\n
          -H 'Accept: application/json' \\\n
          -H 'Content-Type: application/json' -d '\n{\n  \"company_id\": \"acme-corp\",\n  \"title\": \"Quarterly Business Review\",\n  \"description\": \"Q3 review with the customer.\",\n  \"startAt\": \"2024-09-01T10:00:00.000Z\",\n  \"endAt\": \"2024-09-01T11:00:00.000Z\",\n  \"location\": \"https://meet.example.com/qbr\",\n  \"organizer\": {\n    \"name\": \"Jane Smith\",\n    \"email\": \"jane.smith@yourcompany.com\"\n  },\n  \"participants\": [\n    {\n      \"name\": \"John Doe\",\n      \"email\": \"john.doe@acme.com\",\n      \"status\": \"accepted\"\n    }\n  ]\n }'"
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/Meeting"
        description: Meeting object to create or update
        required: true
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (missing required fields)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          description: People or company not found
        '500':
          description: Some other error occurred
      tags: [ "Meetings" ]
    get:
      summary: List meetings
      description: |
        List meetings. To list all the meetings send a `GET` request to [https://api.custify.com/calendar/meeting](https://api.custify.com/calendar/meeting).
        You can send additional query params to filter or paginate results, like:
        - `company_id` (your internal company ID) - filters meetings by which company/companies they are assigned to.
        - `user_id` (your internal user ID) or `email` - filters meetings by which people they are assigned to.
        
        Also you can filter meetings for companies/people by sending a `GET` request to [https://api.custify.com/calendar/meeting/:entityType/:entityId](https://api.custify.com/calendar/meeting/:entityType/:entityId) 
        where `entityType` is the type of the entity (`company` or `people`) and `entityId` is the Custify internal ID of the entity.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/calendar/meeting?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of meetings
                    type: integer
                    example: 1
                  meetings:
                    description: An array of objects with the details of the meetings
                    type: array
                    items:
                      $ref: '#/components/schemas/MeetingsListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Meetings" ]
  "/calendar/meeting/{id}":
    delete:
      summary: Delete a meeting
      description: |
        Delete a meeting by sending a `DELETE` request to [https://api.custify.com/calendar/meeting/{id}](https://api.custify.com/calendar/meeting/{id}),
        where `{id}` is the Custify internal ID of the meeting. Alternatively, you can delete by `externalId` using a query parameter (in which case the `{id}` path parameter can be omitted).
        
        **Note:** If meetings influence touchpoints for the account, this endpoint will automatically recalculate the `lastTouchpointAt` metric for all affected companies.
      parameters:
        - name: id
          in: path
          required: false
          description: The Custify internal ID of the meeting. Optional if using externalId query parameter.
          schema:
            type: string
            example: "5ea93252e0263c08145d6948"
        - name: externalId
          in: query
          required: false
          description: The external ID of the meeting (alternative to internal ID). Use this to delete by external system identifier.
          schema:
            type: string
            example: "google-calendar-event-123"
      x-code-samples:
        - lang: Curl (by internal ID)
          source: "curl 'https://api.custify.com/calendar/meeting/5ea93252e0263c08145d6948' \\\n
                -X DELETE \\\n
                -H 'Authorization: Bearer <Your access token>' \\\n
                -H 'Accept: application/json' \\\n
                -H 'Content-Type: application/json'"
        - lang: Curl (by externalId)
          source: "curl 'https://api.custify.com/calendar/meeting?externalId=google-calendar-event-123' \\\n
                -X DELETE \\\n
                -H 'Authorization: Bearer <Your access token>' \\\n
                -H 'Accept: application/json' \\\n
                -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
        '400':
          description: Bad request (missing required parameter or invalid id format)
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          description: Meeting not found
        '500':
          description: Some other error occurred
      tags: [ "Meetings" ]
  "/calculated_metric":
    get:
      summary: List calculated metrics
      description: |
        List calculated metrics. To list all the calculated metrics send a `GET` request to [https://api.custify.com/calculated_metric](https://api.custify.com/calculated_metric). To get calculated metrics for company/people send a `GET` request to [https://api.custify.com/calculated_metric?type=:type](https://api.custify.com/calculated_metric?type=:type). Default type is `company`.
        To get a specific calculated metric send a `GET` request to [https://api.custify.com/calculated_metric/:id](https://api.custify.com/calculated_metric/:id).
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        },
        {
          $ref: "#/components/parameters/typeParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/calculated_metric?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of calculated metrics
                    type: integer
                    example: 1
                  calculated_metrics:
                    description: An array of objects with the details of the calculated metrics
                    type: array
                    items:
                      $ref: '#/components/schemas/CalculatedMetricsListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Calculated Metrics" ]
  "/health_score":
    get:
      summary: List health scores
      description: |
        List health scores. To list all the health scores send a `GET` request to [https://api.custify.com/health_score](https://api.custify.com/health_score).
        To get a specific health score send a `GET` request to [https://api.custify.com/health_score/:id](https://api.custify.com/health_score/:id).
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/health_score?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of health scores
                    type: integer
                    example: 1
                  health_scores:
                    description: An array of objects with the details of the health scores
                    type: array
                    items:
                      $ref: '#/components/schemas/HealthScoreListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Health Scores" ]
  "/segment":
    get:
      summary: List segments
      description: |
        List segments. To list all the segments send a `GET` request to [https://api.custify.com/segment](https://api.custify.com/segment). To get segments for company/people send a `GET` request to [https://api.custify.com/segment?type=:type](https://api.custify.com/segment?type=:type). Default type is `people`.
        To get a specific segment send a `GET` request to [https://api.custify.com/segment/:id](https://api.custify.com/segment/:id).
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        },
        {
          $ref: "#/components/parameters/typeParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/segment?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of segments
                    type: integer
                    example: 1
                  segments:
                    description: An array of objects with the details of the segments
                    type: array
                    items:
                      $ref: '#/components/schemas/SegmentsListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Segments" ]
  "/lifecycle":
    get:
      summary: List lifecycles
      description: |
        List lifecycles. To list all the lifecycles send a `GET` request to [https://api.custify.com/lifecycle](https://api.custify.com/lifecycle).
        To get a specific lifecycle send a `GET` request to [https://api.custify.com/lifecycle/:id](https://api.custify.com/lifecycle/:id).
        
        ### Filtering lifecycles
        You can apply filters using the `filters` query parameter as an URL-encoded array of objects.
        
        ### Sorting
        By default, lifecycles are sorted by `position` in ascending order. You can customize sorting using the `sort` and `order` parameters.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax200"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/lifecycle?itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of lifecycles
                    type: integer
                    example: 5
                  lifecycles:
                    description: An array of objects with the details of the lifecycles
                    type: array
                    items:
                      $ref: '#/components/schemas/LifecycleListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Lifecycles" ]
  "/playbook":
    get:
      summary: List playbooks
      description: |
        List playbooks. To list all the playbooks send a `GET` request to [https://api.custify.com/playbook](https://api.custify.com/playbook). To get playbooks for company/people send a `GET` request to [https://api.custify.com/playbook?type=:type](https://api.custify.com/playbook?type=:type). Default type is `companies`.
        To get a specific playbook send a `GET` request to [https://api.custify.com/playbook/:id](https://api.custify.com/playbook/:id).
        
        ### Filtering playbooks
        You can apply filters using the `filters` query parameter as an URL-encoded array of objects.
        
        ### Sorting
        By default, playbooks are sorted by `position` in ascending order. You can customize sorting using the `sort` and `order` parameters.
        
        ### Include counts
        By default, the response includes company counts (in_progress, completed, etc.). You can disable this by setting `includeCounts=false`.
      parameters: [
        {
          $ref: "#/components/parameters/itemsPerPageMax200"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        },
        {
          name: "type",
          in: "query",
          description: "Type of playbook (companies or people)",
          schema: {
            type: string,
            enum: [companies, people],
            default: companies,
            example: companies
          }
        },
        {
          name: "nonScheduled",
          in: "query",
          description: "Filter out scheduled playbooks",
          schema: {
            type: boolean,
            default: false,
            example: false
          }
        },
        {
          name: "includeCounts",
          in: "query",
          description: "Include company counts in the response",
          schema: {
            type: boolean,
            default: true,
            example: true
          }
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/playbook?itemsPerPage=20&page=1&type=companies' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of playbooks
                    type: integer
                    example: 8
                  playbooks:
                    description: An array of objects with the details of the playbooks
                    type: array
                    items:
                      $ref: '#/components/schemas/PlaybookListing'
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '500':
          description: Some other error occurred
      tags: [ "Playbooks" ]
  "/objective":
    get:
      summary: List customer objectives
      description: |
        List objectives for a specific company. You must provide either the Custify internal ID of the company via the `company` query parameter, or your internal ID via the `company_id` query parameter.

        Results are paginated and sorted by `created_at` in descending order by default. You can use the `sort` and `order` query parameters to change the sorting. You can also use the `filters` query parameter to filter objectives by status, importance, risk, etc.
      parameters: [
        {
          $ref: "#/components/parameters/companyParam"
        },
        {
          $ref: "#/components/parameters/companyIdParam"
        },
        {
          $ref: "#/components/parameters/itemsPerPageMax50"
        },
        {
          $ref: "#/components/parameters/pageParam"
        },
        {
          $ref: "#/components/parameters/sortingParam"
        },
        {
          $ref: "#/components/parameters/filteringParam"
        }
      ]
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/objective?company_id=123&itemsPerPage=20&page=1' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    description: Total number of objectives for this company
                    type: integer
                    example: 5
                  objectives:
                    description: An array of objective objects
                    type: array
                    items:
                      $ref: '#/components/schemas/ObjectiveListing'
                  page:
                    description: Current page number
                    type: integer
                    example: 1
                  itemsPerPage:
                    description: Number of items per page
                    type: integer
                    example: 20
        '400':
          description: Bad request - missing company or company_id query parameter
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '404':
          description: Company not found
        '500':
          description: Some other error occurred
      tags: [ "Customer Objectives" ]
  "/person_company_relationship/people/{personId}":
    get:
      summary: List a person's company relationships
      description: |
        Returns every company relationship for a single person by sending a GET request to [https://api.custify.com/person_company_relationship/people/{personId}](https://api.custify.com/person_company_relationship/people/{personId}), where `{personId}` is the Custify internal `id` of the person.

        Requires **company-dependent people roles** to be enabled for your account.
      parameters:
        - name: personId
          in: path
          description: The Custify internal `id` of the person.
          required: true
          schema:
            type: string
          example: "5b9f95d838ab5e09b8ed66cb"
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/person_company_relationship/people/5b9f95d838ab5e09b8ed66cb' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/PersonCompanyRelationship"
                  total:
                    type: integer
                    example: 2
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '403':
          description: Company-dependent people roles are not enabled for this account
        '500':
          description: Some other error occurred
      tags: [ "Person-Company Relationships" ]
  "/person_company_relationship/company/{companyId}":
    get:
      summary: List a company's people relationships
      description: |
        Returns the people relationships for a single company by sending a GET request to [https://api.custify.com/person_company_relationship/company/{companyId}](https://api.custify.com/person_company_relationship/company/{companyId}), where `{companyId}` is the Custify internal `id` of the company. The response is paginated and ordered by `created_at` descending by default.

        The `sort` parameter accepts one of `created_at`, `updated_at`, `role` or `linked_at`; any other value falls back to `created_at`. The `order` parameter accepts `asc` or `desc`.

        Requires **company-dependent people roles** to be enabled for your account.
      parameters:
        - name: companyId
          in: path
          description: The Custify internal `id` of the company.
          required: true
          schema:
            type: string
          example: "5b9f95d838ab5e09b8ed66cb"
        - $ref: "#/components/parameters/pageParam"
        - $ref: "#/components/parameters/limitParam"
        - name: sort
          in: query
          description: Sort field. One of `created_at`, `updated_at`, `role`, `linked_at`. Defaults to `created_at`.
          schema:
            type: string
            enum: [created_at, updated_at, role, linked_at]
          example: "role"
        - $ref: "#/components/parameters/orderParam"
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/person_company_relationship/company/5b9f95d838ab5e09b8ed66cb?page=1&itemsPerPage=20&sort=role&order=asc' \\\n
                      -X GET \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/PersonCompanyRelationship"
                  total:
                    type: integer
                    example: 42
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '403':
          description: Company-dependent people roles are not enabled for this account
        '500':
          description: Some other error occurred
      tags: [ "Person-Company Relationships" ]
  "/person_company_relationship/people/{personId}/{companyId}":
    post:
      summary: Create or update a relationship
      description: |
        Creates or updates the relationship between a person and a company by sending a POST request to [https://api.custify.com/person_company_relationship/people/{personId}/{companyId}](https://api.custify.com/person_company_relationship/people/{personId}/{companyId}). If a relationship already exists for the pair it is updated; otherwise it is created.

        The person must already be linked to the company, otherwise the request returns `400`. The `role` value must be one of the role values configured for your account, and any `custom_attributes` keys must match configured `people-company-attribute` definitions; invalid values return `400`.

        Requires **company-dependent people roles** to be enabled for your account.
      parameters:
        - name: personId
          in: path
          description: The Custify internal `id` of the person.
          required: true
          schema:
            type: string
          example: "5b9f95d838ab5e09b8ed66cb"
        - name: companyId
          in: path
          description: The Custify internal `id` of the company.
          required: true
          schema:
            type: string
          example: "5ed60ea90494f32ff3959079"
      requestBody:
        description: Relationship fields to set. All fields are optional.
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PersonCompanyRelationshipRequest"
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/person_company_relationship/people/5b9f95d838ab5e09b8ed66cb/5ed60ea90494f32ff3959079' \\\n
                      -X POST \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json' -d ' \n{\n  \"role\": \"Billing Contact\",\n  \"linked_at\": \"2024-01-15\",\n  \"custom_attributes\": {\n    \"seat_count\": 5\n  }\n}'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: "#/components/schemas/PersonCompanyRelationship"
        '400':
          description: Person is not linked to this company, invalid role, or invalid custom attribute
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '403':
          description: Company-dependent people roles are not enabled for this account
        '500':
          description: Some other error occurred
      tags: [ "Person-Company Relationships" ]
    delete:
      summary: Delete a relationship
      description: |
        Removes the relationship between a person and a company by sending a DELETE request to [https://api.custify.com/person_company_relationship/people/{personId}/{companyId}](https://api.custify.com/person_company_relationship/people/{personId}/{companyId}). The person and company records themselves are not affected.

        Requires **company-dependent people roles** to be enabled for your account.
      parameters:
        - name: personId
          in: path
          description: The Custify internal `id` of the person.
          required: true
          schema:
            type: string
          example: "5b9f95d838ab5e09b8ed66cb"
        - name: companyId
          in: path
          description: The Custify internal `id` of the company.
          required: true
          schema:
            type: string
          example: "5ed60ea90494f32ff3959079"
      x-code-samples:
        - lang: Curl
          source: "curl 'https://api.custify.com/person_company_relationship/people/5b9f95d838ab5e09b8ed66cb/5ed60ea90494f32ff3959079' \\\n
                      -X DELETE \\\n
                      -H 'Authorization: Bearer <Your access token>' \\\n
                      -H 'Accept: application/json' \\\n
                      -H 'Content-Type: application/json'"
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
        '401':
          $ref: "#/components/responses/AccessForbidden"
        '403':
          description: Company-dependent people roles are not enabled for this account
        '500':
          description: Some other error occurred
      tags: [ "Person-Company Relationships" ]
components:
  securitySchemes:
    BearerAUTH:
      type: http
      scheme: bearer
      bearerFormat: Bearer <API_KEY>
  parameters:
    resourceId:
      name: id
      in: path
      description: The Custify internal resource identifier string.
      schema:
        type: string
      required: true
      example: "5b9f95d838ab5e09b8ed66cb"
    resourceIdOptional:
      name: id
      in: path
      description: The Custify internal resource identifier string.
      schema:
        type: string
      example: "5b9f95d838ab5e09b8ed66cb"
    batchJobId:
      name: id
      in: path
      description: ID of the batch job id.
      schema:
        type: string
      example: "35757461-c988-5508-9f80-68bd45a99bf9"
    ticketExternalId:
      name: ticketExternalId
      in: path
      description: External ID of the ticket.
      schema:
        type: string
      example: "ab"
    financialExternalId:
      name: externalId
      in: path
      description: External ID of the financial entity (deal, invoice or subscription).
      schema:
        type: string
      example: "abc"
    limitParam:
      name: itemsPerPage
      in: query
      description: The resource number of items per page. Default value is `20`.
      schema:
        type: integer
      example: 25
    itemsPerPageMax50:
      name: itemsPerPage
      in: query
      description: The resource number of items per page.
      schema:
        type: integer
        maximum: 50
        default: 20
      example: 20
    itemsPerPageMax200:
      name: itemsPerPage
      in: query
      description: The resource number of items per page.
      schema:
        type: integer
        maximum: 200
        default: 20
      example: 20
    pageParam:
      name: page
      in: query
      description: The resource current page.
      schema:
        type: integer
        default: 1
      example: 7
    typeParam:
      name: type
      in: query
      description: The type of the resource.
      schema:
        type: string
      example: "company"
    sortingParam:
      name: sorting
      in: query
      description: "The resource items sorting object. This param should be an object, like: {\"field\": \"updated_at\", \"direction\": \"desc\"} and must be encoded."
      schema:
        type: object
    sortParam:
      name: sort
      in: query
      description: The resource items sort field.
      schema:
        type: string
      example: "updated_at"
    orderParam:
      name: order
      in: query
      description: The resource items order direction.
      schema:
        type: string
      example: "asc"
    categoryParam:
      name: category
      in: query
      description: The resource items category.
      schema:
        type: string
        default: "all"
      example: "company"
    filteringParam:
      name: filters
      in: query
      description: The resource items filters.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/ListingFilter'
    includeSegmentsParam:
      name: includeSegments
      in: query
      description: If this field is set to `true` the response will include the segments of the resource. Default value is `false`. In the response, the segments will be in the `segments` field and will be an array of objects each one containing the fields `id` (the ID of the segment) and `name` (the name of the segment).
      schema:
        type: string
        default: "false"
    filteringProperties:
      name: properties
      in: query
      description: The resource items properties that will be returned (if they exist). If not set, all properties will be returned.
      schema:
        type: array
        example: ["name", "email"]
    filteringTaskParam:
      name: filters
      in: query
      description: The resource items filters.
      schema:
        type: array
        items:
          $ref: '#/components/schemas/ListingTaskFilter'
    userIdParam:
      name: user_id
      in: query
      description: Your internal `user_id`.
      schema:
        type: string
      example: "36"
    userParamRequired:
      name: user
      in: query
      description: The email address of the user or the Custify internal ID of the user.
      schema:
        type: string
      required: true
      example: "john.doe@example.com"
    emailParam:
      name: email
      in: query
      description: Person `email` address.
      schema:
        type: string
      example: "john.doe_at_example.com"
    companyParam:
      name: company
      in: query
      description: The Custify internal ID of the company.
      schema:
        type: string
      example: "5b9f95d838ab5e09b8ed66cb"
    companyIdParam:
      name: company_id
      in: query
      description: Your internal ID of the company.
      schema:
        type: string
      example: "2345"
    entityModel:
      name: entityModel
      in: path
      description: companies or people, depending on the entity type
      schema:
        type: string
      required: true
      example: "companies"
    entity:
      name: entity
      in: path
      description: The Custify internal entity ID.
      schema:
        type: string
      required: true
      example: "5b9f95d838ab5e09b8ed66cb"
    entityFinancial:
      name: entity
      in: path
      description: The Custify internal entity ID of the financial entity (deal, invoice or subscription).
      schema:
        type: string
      example: "5b9f95d838ab5e09b8ed66cb"
    entityNotRequired:
      name: entity
      in: path
      description: The Custify internal entity ID.
      schema:
        type: string
      example: "5b9f95d838ab5e09b8ed66cb"
    entityModelComment:
      name: entityModel
      in: path
      description: Note or Task, depending on the entity type
      schema:
        type: string
      required: true
      example: "Note"
    companyIdQuery:
      name: companyId
      in: query
      description: Custify internal ID of the company.
      schema:
        type: string
      example: "5b9f95d838ab5e09b8ed66cb"
    peopleIdQuery:
      name: peopleId
      in: query
      description: Custify internal ID of the people.
      schema:
        type: string
      example: "5b9f95d838ab5e09b8ed66cc"
    searchKeyQuery:
      name: searchKey
      in: query
      description: Search string to be used in filtering file names.
      schema:
        type: string
      example: "document"
  responses:
    AccessForbidden:
      description: "Access forbidden, invalid API-KEY was used"
    Conflict:
      description: "There's a conflict with the expected format or details that need to be sent in the request"
    NotFound:
      description: "Resource was not found"
  schemas:
    PersonCompanyRelationship:
      type: object
      description: A link between one person and one company, holding the person's role and relationship-specific attributes at that company.
      properties:
        person:
          description: The Custify internal `id` of the person.
          type: string
          example: "5b9f95d838ab5e09b8ed66cb"
        company:
          description: The Custify internal `id` of the company.
          type: string
          example: "5ed60ea90494f32ff3959079"
        role:
          description: The person's role at this company. One of the role values configured for your account, or `null` if unset.
          type: string
          nullable: true
          example: "Billing Contact"
        linked_at:
          description: The date the person joined the company. Set only when the relationship is created.
          type: string
          format: date-time
          nullable: true
          example: "2024-01-15T00:00:00.000Z"
        custom_attributes:
          description: Relationship-specific custom attributes. Each key must match a configured `people-company-attribute`.
          type: object
          additionalProperties: true
          example:
            seat_count: 5
        created_at:
          type: string
          format: date-time
          example: "2024-01-15T09:12:33.001Z"
        updated_at:
          type: string
          format: date-time
          example: "2024-02-02T11:45:10.420Z"
    PersonCompanyRelationshipRequest:
      type: object
      description: Fields accepted when creating or updating a person-company relationship. All fields are optional.
      properties:
        role:
          description: The person's role at this company. Must be one of the role values configured for your account. Pass `null` to clear the role.
          type: string
          nullable: true
          example: "Billing Contact"
        linked_at:
          description: The date the person joined the company. Applied only when the relationship is first created. Accepts any supported ISO 8601 date format (for example `2024-01-15`).
          type: string
          format: date-time
          example: "2024-01-15T00:00:00.000Z"
        custom_attributes:
          description: Relationship-specific custom attributes. Each key must match a configured `people-company-attribute`.
          type: object
          additionalProperties: true
          example:
            seat_count: 5
    People:
      type: object
      properties:
        user_id:
          description: A unique string identifier for people. Required on creation if an email isn't supplied.
          type: string
          example: "25"
        email:
          description: The person's email address. Required on creation if a user_id is not supplied.
          type: string
          example: "john.doe@mail.com"
        phone:
          description: The person's phone number.
          type: string
          example: "+44 7911 123456"
        signed_up_at:
          description: The person's signup date or date the contract started.
          type: string
          format: date-time
          example: "2019-05-30T12:00:00.000Z"
        name:
          description: The person's full name.
          type: string
          example: "John Doe"
        session_count:
          description: The person's session count.
          type: integer
          example: 2
        companies:
          description: A list of companies you wish to assign; usually, this is one company.
          type: array
          example: [ { "company_id": "366" } ]
        custom_attributes:
          description: A hash of key/value pairs containing any other data you want to store in Custify.
          type: object
          example: { "bool_paid_subscriber": true, "int_team_mates": 5, "string_plan": "advanced", "date_example_date_at": "2019-06-30T12:00:00.000Z" }
        unsubscribed_from_emails:
          description: A Boolean value representing the person's unsubscribed status from emails that you've collected from other systems. Default value is false.
          type: boolean
          default: false
        unsubscribed_from_calls:
          description: A Boolean value representing the person's unsubscribed status from calls that you have collected from other systems. Default value is false.
          type: boolean
          default: false
    PeopleTag:
      type: object
      properties:
        ids:
          description: And array of Custify internal ids of the people you want to add/remove a tag.
          type: array
          example: [ "5d402cf8c3a4c5578c9be5f4", "5d11c88ca6674a2541ade9b8" ]
        type:
          description: Available types (add or remove).
          type: string
          example: "add"
        tag:
          description: The Custify internal id of the tag.
          type: string
          example: "5d948817c5f9442ea5482321"
    Event:
      type: object
      required:
        - name
        - created_at
      properties:
        name:
          description: Name of the event.
          type: string
          example: "login"
        created_at:
          description: The time the event occurred in your application.
          type: string
          format: date-time
          example: "2019-07-01T12:00:00.000Z"
        user_id:
          description: A unique String identifier for the person, created via the "people" API. Required if no email is present.
          type: string
          example: "1"
        company_id:
          description: A unique String identifier for the company, created via the "companies" API. Optional.
          type: string
          example: "20"
        email:
          description: The person's email address, previously created via the "people" API. Required if no user_id is present.
          type: string
          example: "test@example.org"
        deduplication_id:
          description: An identifier of the event. If present, subsequent events with the same identifier will be ignored
          type: string
          example: "5d95ecc9749204521d2e3945"
        metadata:
          description: Optional metadata about the event.
          type: object
          example: { "email": "john@example.org", "code": "ABCDEF" }
    Company:
      type: object
      properties:
        company_id:
          description: The company id you've defined for the company.
          type: string
          example: "6"
        name:
          description: The name of the company.
          type: string
          example: Pizzeria Presto
        signed_up_at:
          description: The company signup date or date the contract started.
          type: string
          format: date-time
          example: "2019-05-30T12:00:00.000Z"
        size:
          description: The number of employees in this company.
          type: integer
          example: 15
        website:
          description: The URL for this company's website.
          type: string
          example: www.pizzeriapresto.com
        industry:
          description: The industry that this company operates in.
          type: string
          example: Restaurant
        plan:
          description: The plan this company is subscribed to.
          type: string
          example: Platinum
        monthly_revenue:
          description: How much revenue the company generates for your business.
          type: integer
          example: 1234567
        churned:
          description: Defines if a company has churned. Default value is false; if set to true, company will be considered as churned.
          type: boolean
          default: false
        owners_csm:
          description: The email adderess of the CSM assigned to this company. A user with this email must exist in Custify to be assigned.
          type: string
          example: "john.doe@mail.com"
        owners_account:
          description: The email adderess of the Account manager assigned to this company. A user with this email must exist in Custify to be assigned.
          type: string
          example: "john.doe@mail.com"
        parent_companies:
          description: An array of IDs of the parent_companies associated with the current company.
          type: array
          example: [ { "id": "5ec50c9829d3c17c7cf455f2" }, { "id": "5ec50c9829d3c17c7cf457f2" } ]
        custom_attributes:
          description: A JSON object of key/value pairs containing any other data about the company.
          type: object
          example: { "restaurants": 5, "custom": "template" }
    Note:
      type: object
      required:
        - text
        - entity
        - entityModel
      properties:
        text:
          description: Text of the note.
          type: string
          example: "First note"
        entity:
          description: The Custify internal id of the entity (Customer or Company).
          type: string
          example: "5ed60ea90494f32ff3959079"
        entityModel:
          description: Customer (for People) or Company.
          type: string
          example: "Company"
        sticky:
          description: Mark if the note it's sticky or not. Default is `false`.
          type: boolean
          example: false
        tags:
          type: array
          description: An array of the tags to apply to the note. Valid tag IDs are Custify internal IDs tags having category `note`
          items:
            $ref: '#/components/schemas/TagsList'
        files:
          description: An array of file ids that are attached to the note
          type: array
          items:
            $ref: '#/components/schemas/FileList'
        showInPortal:
          description: Mark if the note should be shown in the portal. Default is `false`.
          type: boolean
          example: false
        metadata:
          type: object
          description: An object with some extra metadata for notes
          properties:
            mentionedUsers:
              description: An array of mentioned users in the note. The array may contain Custify user IDs or email of the user
              type: array
              items:
                $ref: '#/components/schemas/NoteMentionedUsers'
    Tag:
      type: object
      required:
        - name
        - category
      properties:
        name:
          description: Text of the tag.
          type: string
          example: "First tag"
        description:
          description: The description of the tag.
          type: string
          example: "First tag description"
        category:
          description: The category of the tag
          type: string
          enum:
            - people
            - company
            - task
            - note
            - segment
            - playbook
            - lifecycle
            - health_score
            - survey
            - calculated_metric
    TagEntity:
      type: object
      required:
        - ids
        - type
        - category
        - tag
      properties:
        ids:
          description: An array of Custify internal IDs of the entities that needs to be updated.
          type: array
          example: [ "634523fe5418640067e1031a", "6322e4cf0d47b2d3eb97811d" ]
        type:
          description: Type of the operation to be applied to the tag for the entities.
          type: string
          enum:
            - add
            - remove
        category:
          description: The category of the tag
          type: string
          enum:
            - people
            - company
            - task
            - note
            - segment
            - playbook
            - lifecycle
            - health_score
            - survey
            - calculated_metric
        tag:
          description: The Custify internal ID of the tag.
          type: string
          example: "6345240b5418640067e1033a"
    CustomData:
      type: object
      required:
        - data_type
        - data_id
        - data
      properties:
        data_type:
          description: The type of custom data object
          type: string
          example: "invoice"
        data_id:
          description: Your ID for the custom data object
          type: string
          example: "INV_001"
        data:
          description: Key-value list of the custom data object properties
          type: object
          example: { "amount": 123, "is_paid": true, "plan": "advanced", "invoiced_at": "2019-06-30T12:00:00.000Z" }
    NPSScore:
      type: object
      required:
        - score
      properties:
        score:
          description: The score for the NPS score
          type: integer
          example: 9
        comment:
          description: The comment for the NPS score
          type: string
          example: "Almost perfect"
        submittedAt:
          description: Date for the NPS score
          type: string
          format: date-time
          example: "2021-04-10T12:00:00.000Z"
        surveyId:
          description: The survey id for the NPS score
          type: string
          example: "5d402cf8c3a4c5578c9be5f4"
    CSATScore:
      type: object
      required:
        - score
      properties:
        score:
          description: The score for the CSAT score (typically 1-5)
          type: integer
          minimum: 1
          maximum: 5
          example: 5
        comment:
          description: The comment for the CSAT score
          type: string
          example: "Very satisfied"
        submittedAt:
          description: Date for the CSAT score
          type: string
          format: date-time
          example: "2021-04-10T12:00:00.000Z"
        surveyId:
          description: The survey id for the CSAT score
          type: string
          example: "5d402cf8c3a4c5578c9be5f4"
    Batch:
      type: object
      properties:
        jobs:
          description: The jobs array of objects
          type: array
          example: [ { "type": "people", "payload": { "name": "John Doe", "user_id": "batch_1", "email": "john.doe@outlook.com" } },{ "type": "company", "payload": { "name": "John's Company", "company_id": "batch_company_1", "website": "www.johnscompany.com" } },{ "type": "event", "payload": { "name": "event_from_batch", "user_id": "batch_1", "created_at": "2022-01-17T13:00:00.000Z" } },{ "type": "custom-data","payload": { "entity": "65240f85e2a675bd3090a3d3","entityModel": "Company","data_type": "invoice","data_id": "INV_003","data": { "amount": 175,"invoiced_at": "2023-02-02T00:00:00Z","is_paid": false,"product_name": "bronze_plan" } } } ]
        synchronous:
          description: The type of the processing
          type: boolean
          example: false
        returnJobId:
          description: The job id of the processing used in case synchronous is false
          type: boolean
          example: false
    Ticket:
      type: object
      properties:
        externalId:
          description: The external ID of the ticket (used in your system).
          type: string
          example: "ab"
        title:
          description: The title of the ticket
          type: string
          example: "First ticket"
        description:
          description: The description of the ticket
          type: string
          example: "Description of the ticket"
        ticketStatus:
          description: The status of the ticket
          type: string
          example: "open"
        priority:
          description: The priority of the ticket
          type: string
          example: "high"
        openedAt:
          description: The date the ticket was opened
          type: string
          format: date-time
          example: "2021-04-10T12:00:00.000Z"
        lastModifiedAt:
          description: The date the ticket was last modified
          type: string
          format: date-time
          example: "2021-05-10T12:00:00.000Z"
        assignedToName:
          description: The name of the person that the ticket is assigned to
          type: string
          example: "John"
        company:
          description: The company id you've defined for the company.
          type: string
          example: "6"
        people:
          description: The user_id or the email you've defined for the people.
          type: string
          example: "15"
        replies:
          description: The replies to the ticket
          type: array
          example: [ { "type": "note|incoming|outgoing", "from": "John", "body": "Take a look", "submittedAt": "2021-05-10T12:00:00.000Z" } ]
    TicketReply:
      type: object
      properties:
        type:
          description: The type of the reply. Available values are note, incoming and outgoing.
          type: string
          example: "note"
        from:
          description: The name of the person from where the reply is coming.
          type: string
          example: "John"
        body:
          description: The body of the reply.
          type: string
          example: "Take a look"
        submittedAt:
          description: The date the reply was submitted
          type: string
          format: date-time
          example: "2021-05-10T12:00:00.000Z"
    TicketListing:
      type: object
      properties:
        id:
          description: Custify's internal ID of the ticket
          type: string
          example: "5ea93252e0263c08145d6945"
        externalId:
          description: The external ID of the ticket (used in your system)
          type: string
          example: "TICKET-123"
        provider:
          description: The provider/source system of the ticket
          type: string
          example: "zendesk"
        company:
          description: Array of Custify internal IDs of the companies associated with the ticket
          type: array
          items:
            type: string
          example: ["5ea93252e0263c08145d6944"]
        companyNames:
          description: Array of company name objects associated with the ticket (enriched data)
          type: array
          items:
            type: object
          example: [{ "forte": "Acme Corp" }]
        people:
          description: Array of people objects associated with the ticket
          type: array
          items:
            type: object
            properties:
              id:
                type: string
          example: [{ "id": "60b4d002e1a59a7c74531fcad" }]
        peopleNames:
          description: Array of people names associated with the ticket (enriched data)
          type: array
          items:
            type: string
          example: ["John Doe"]
        title:
          description: The title of the ticket
          type: string
          example: "Login issue with mobile app"
        description:
          description: The description of the ticket
          type: string
          example: "User is unable to login using their credentials on the mobile app"
        ticketStatus:
          description: The status of the ticket
          type: string
          example: "open"
        status:
          description: The internal status of the ticket (active or inactive)
          type: string
          enum: [active, inactive]
          example: "active"
        priority:
          description: The priority of the ticket
          type: string
          example: "high"
        assignedTo:
          description: The identifier of the person the ticket is assigned to
          type: string
          example: "john.doe@example.com"
        assignedToName:
          description: The name of the person the ticket is assigned to
          type: string
          example: "John Doe"
        openedAt:
          description: The date the ticket was opened
          type: string
          format: date-time
          example: "2021-04-10T12:00:00.000Z"
        ratingAt:
          description: The date the ticket was rated
          type: string
          format: date-time
          example: "2021-04-15T12:00:00.000Z"
        lastModifiedAt:
          description: The date the ticket was last modified
          type: string
          format: date-time
          example: "2021-05-10T12:00:00.000Z"
        rating:
          description: The rating given to the ticket
          type: string
          example: "5"
        tags:
          description: Array of tag IDs associated with the ticket
          type: array
          items:
            type: string
          example: ["5d11d5687113bc33f07573f0"]
        created_at:
          description: The date the ticket was created in Custify
          type: string
          format: date-time
          example: "2021-04-10T12:00:00.000Z"
        updated_at:
          description: The date the ticket was last updated in Custify
          type: string
          format: date-time
          example: "2021-05-10T12:00:00.000Z"
    Task:
      type: object
      required:
        - name
        - priority
        - status
      properties:
        name:
          description: The name of the task
          type: string
          example: "First task"
        externalId:
          description: Your internal task ID
          type: string
          example: "abc"
        description:
          description: The description of the task
          type: string
          example: "Description of the task"
        company:
          description: Custify's internal ID of the company for which the task is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        company_id:
          description: Your internal identifier of the company
          type: string
          example: "20"
        people:
          description: Custify's internal ID of the people from the company for which the task is created/updated
          type: string
          example: "5ea93252e0263c08145d6945"
        user_id:
          description: Your internal identifier of the people
          type: string
          example: "20"
        assignedTo:
          description: Custify's internal ID of the user to which the task is assigned. It can be also the email of the user
          type: string
          example: "john.doe@test.com"
        assignedToCustomer:
          description: Field value is set to true if the task is assigned to a customer
          type: boolean
          example: false
        priority:
          description: The priority of the task
          type: string
          enum:
            - low
            - medium
            - high
          example: "medium"
        dueDate:
          description: The due date of the task
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        status:
          description: The status of the task
          type: string
          enum:
            - open
            - done
            - not relevant
          default: open
          example: "open"
        tags:
          type: array
          description: An array of the tags to apply to the task. Valid tag IDs are Custify internal IDs tags having category `task`
          items:
            $ref: '#/components/schemas/TagsList'
        checklist:
          description: An array of checklist objects that are attached to the task
          type: array
          items:
            $ref: '#/components/schemas/TaskChecklist'
        files:
          description: An array of file ids that are attached to the task
          type: array
          items:
            $ref: '#/components/schemas/FileList'
        showInPortal:
          description: Mark if the task should be shown in the portal. Default is `false`.
          type: boolean
          example: false
        collaborators:
          description: An array of Custify internal IDs of the people that are collaborators on the task. It also accepts the email of the user.
          type: array
          items:
            type: string
            example: "5ea93252e0263c08145d6945"
    TaskUpdate:
      type: object
      required:
        - _id
      properties:
        _id:
          description: Custify's internal ID of the task to be updated
          type: string
          example: "5ea93252e0263c08145d6945"
        externalId:
          description: Your internal ID of the task to be updated
          type: string
          example: "abc"
        name:
          description: The name of the task
          type: string
          example: "First task"
        description:
          description: The description of the task
          type: string
          example: "Description of the task"
        company:
          description: Custify's internal ID of the company for which the task is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        company_id:
          description: Your internal identifier of the company
          type: string
          example: "20"
        people:
          description: Custify's internal ID of the people from the company for which the task is created/updated
          type: string
          example: "5ea93252e0263c08145d6945"
        user_id:
          description: Your internal identifier of the people
          type: string
          example: "20"
        assignedTo:
          description: Custify's internal ID of the user to which the task is assigned. It can be also the email of the user
          type: string
          example: "john.doe@test.com"
        assignedToCustomer:
          description: Field value is set to true if the task is assigned to a customer
          type: boolean
          example: false
        priority:
          description: The priority of the task
          type: string
          enum:
            - low
            - medium
            - high
          example: "medium"
        dueDate:
          description: The due date of the task
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        status:
          description: The status of the task
          type: string
          enum:
            - open
            - done
            - not relevant
          default: open
          example: "open"
        tags:
          description: An array of the tags to apply to the task. Valid tag IDs are Custify internal IDs tags having category `task`
          items:
            $ref: '#/components/schemas/TagsList'
        checklist:
          description: An array of checklist objects that are attached to the task
          type: array
          items:
            $ref: '#/components/schemas/TaskChecklist'
        files:
          description: An array of file ids that are attached to the task
          type: array
          items:
            $ref: '#/components/schemas/FileList'
        showInPortal:
          description: Mark if the task should be shown in the portal. Default is `false`.
          type: boolean
          example: false
        collaborators:
          description: An array of Custify internal IDs of the people that are collaborators on the task. It also accepts the email of the user.
          type: array
          items:
            type: string
            example: "5ea93252e0263c08145d6945"
    CustomDataListing:
      type: object
      required:
        - data_type
        - data_id
        - data
      properties:
        data_type:
          description: The data type of the custom data
          type: string
          example: "messages"
        data_id:
          description: The data id of the custom data
          type: string
          example: "MSG_001"
        data:
          description: The data object of the custom data
          type: object
          example: { "campaign": 1, "opened": false, "priority": "high",  "scheduled": "2020-12-02T00:00:00.000Z" }
    TaskListing:
      type: object
      required:
        - id
        - name
        - priority
        - status
      properties:
        id:
          description: Custify's internal ID of the task
          type: string
          example: "5ea93252e0263c08145d6945"
        externalId:
          description: Your internal ID of the task
          type: string
          example: "abc"
        name:
          description: The name of the task
          type: string
          example: "First task"
        description:
          description: The description of the task
          type: string
          example: "Description of the task"
        company:
          description: Custify's internal ID of the company for which the task is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        company_id:
          description: Your internal identifier of the company
          type: string
          example: "20"
        people:
          description: Custify's internal ID of the people from the company for which the task is created/updated
          type: string
          example: "5ea93252e0263c08145d6945"
        user_id:
          description: Your internal identifier of the people
          type: string
          example: "20"
        assignedTo:
          description: Custify's internal ID of the user to which the task is assigned
          type: string
          example: "5ea93252e0263c08145d6946"
        assignedToName:
          description: The name of the user to which the task is assigned
          type: string
          example: "John Doe Sr."
        assignedToEmail:
          description: The email of the user to which the task is assigned
          type: string
          example: "john.doe.sr@example.com"
        assignedToCustomer:
          description: Field value is `true` if the user to which the task is assigned is a customer
          type: boolean
          example: false
        priority:
          description: The priority of the task
          type: string
          enum:
            - low
            - medium
            - high
          example: "medium"
        dueDate:
          description: The due date of the task
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        status:
          description: The status of the task
          type: string
          enum:
            - open
            - done
            - not relevant
          default: open
          example: "open"
        tags:
          description: An array of the tags to apply to the task. Valid tag IDs are Custify internal IDs tags having category `task`
          items:
            $ref: '#/components/schemas/TagsList'
        checklist:
          description: An array of checklist objects that are attached to the task
          type: array
          items:
            $ref: '#/components/schemas/TaskChecklist'
        files:
          description: An array of file ids that are attached to the task
          type: array
          items:
            $ref: '#/components/schemas/FileList'
        created_at:
          description: The date the task was created
          format: date-time
          example: "2023-10-01T12:00:00.000Z"
        updated_at:
          description: The date the task was last updated
          format: date-time
          example: "2023-10-01T12:00:00.000Z"
        completedAt:
          description: The date the task was completed
          format: date-time
          example: "2023-10-01T12:00:00.000Z"
        completedBy:
          description: Custify's internal ID of the user that completed the task
          type: string
          example: "5ea93252e0263c08145d6946"
        completedByName:
          description: The name of the user that completed the task
          type: string
          example: "John Doe Sr."
        showInPortal:
          description: Mark if the task should be shown in the portal. Default is `false`.
          type: boolean
          example: false
        collaborators:
          description: An array of collaborators (Custify ID of the user) for the task
          type: array
          example: [ "5ea93252e0263c08145d6946", "5ea93252e0263c08145d6947" ]
        collaboratorsDetailed:
          description: An array of collaborators for the task with detailed information
          type: array
          items:
            $ref: '#/components/schemas/TaskCollaboratorsDetailed'
    TaskCompanyFilter:
      type: object
      required:
        - name
        - id
      properties:
        name:
          description: The name of the company
          type: string
          example: "Company One"
        id:
          description: Custify's internal ID of the company
          type: string
          example: "5ea93252e0263c08145d6945"
    TaskAssignedtoFilter:
      type: object
      required:
        - id
        - name
      properties:
        id:
          description: Custify's internal ID of the user
          type: string
          example: "5ea93252e0263c08145d6945"
        name:
          description: The name of the user
          type: string
          example: "User One"
    TaskCreatedbyFilter:
      type: object
      required:
        - id
        - name
      properties:
        id:
          description: Custify's internal ID of the user/lifecycle/playbook
          type: string
          example: "5ea93252e0263c08145d6945"
        name:
          description: The name of the user/lifecycle/playbook
          type: string
          example: "User One"
    TaskTagsFilter:
      type: object
      required:
        - id
      properties:
        id:
          description: Custify's internal ID of the tag
          type: string
          example: "5ea93252e0263c08145d6945"
    TaskChecklist:
      type: object
      required:
        - name
        - completed
      properties:
        name:
          description: The name of the checklist item
          type: string
          example: "Item 1"
        completed:
          description: The status of the checklist item
          type: boolean
          example: false
        dueDate:
          description: The due date of the checklist item
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        assignedTo:
          description: Custify's internal ID of the user to which the checklist item is assigned. It can be also the email of the user
          type: string
          example: "5ea93252e0263c08145d6946"
    TaskCollaboratorsDetailed:
      type: object
      required:
        - id
        - name
        - email
      properties:
        id:
          description: Custify's internal ID of the user
          type: string
          example: "5ea93252e0263c08145d6945"
        name:
          description: The name of the user
          type: string
          example: "User One"
        email:
          description: The email of the user
          type: string
          example: "user_one@example.com"
    TagsList:
      type: string
      example: "5d11d5687113bc33f07573f0"
    NoteMentionedUsers:
      type: string
      example: "5d11d5687113bc33f07573f0"
    ListingFilter:
      type: object
      required:
        - fieldName
        - fieldType
        - filterType
        - filterValue
      properties:
        fieldName:
          description: The name of the field to be filtered
          type: string
          example: "name"
        fieldType:
          description: The type of the field to be filtered
          type: string
          example: "String"
        filterType:
          description: The type of the filter to be applied to the field
          type: string
          example: "contains"
        filterValue:
          description: The value of the filter to be applied to the field
          type: string
          example: "a"
    ListingTaskFilter:
      type: object
      required:
        - field
        - values
      properties:
        field:
          description: The name of the field to be filtered
          type: string
          example: "createdBy"
        values:
          description: The values of the field to be filtered
          type: array
    ListingTicketFilter:
      type: object
      required:
        - field
        - values
      properties:
        field:
          description: The name of the field to be filtered
          type: string
          example: "ticketStatus"
        values:
          description: The values of the field to be filtered
          type: array
          items:
            type: string
          example: ["open", "pending"]
    Comment:
      type: object
      required:
        - text
      properties:
        text:
          description: Comment's text.
          type: string
          example: "First comment"
        id:
          description: ID of the comment (used to update an existing comment).
          type: string
          example: "5ed60ea90494f32ff3959079"
        createdBy:
          description: Custify's internal ID of the user which left the comment. It can be also the email of the user
          type: string
          example: "john.doe@test.com"
    CommentListing:
      type: object
      properties:
        entity:
          description: The Custify internal id of the entity (Note or Task).
          type: string
          example: "5ed60ea90494f32ff3959079"
        entityModel:
          description: Note or Task.
          type: string
          example: "Note"
        text:
          description: Comment's text.
          type: string
          example: "First comment"
        createdBy:
          description: Custify's internal ID of the user which left the comment.
          type: string
          example: "5ed60ea90494f32ff3959079"
    FinancialDeal:
      type: object
      required:
        - externalId
      properties:
        externalId:
          description: Your internal ID of the financial deal.
          type: string
          example: "deal01"
        company:
          description: Custify's internal ID of the company for which the financial deal is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        company_id:
          description: Your internal identifier of the company
          type: string
          example: "20"
        people:
          description: Custify's internal ID of the people for which the financial deal is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        user_id:
          description: Your internal identifier of the people
          type: string
          example: "20"
        name:
          description: The name of the financial deal.
          type: string
          example: "deal01"
        status:
          description: The status of the financial deal.
          type: string
          example: "won"
        value:
          description: The value of the financial deal.
          type: integer
          example: 199
        addedAt:
          description: The date the financial deal was added.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        wonAt:
          description: The date the financial deal was won.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        lostAt:
          description: The date the financial deal was lost.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
    FinancialDealListing:
      type: object
      properties:
        externalIds:
          description: An object containing details about sources from where the deal came. In this object is saved the `externalId` you send.
          type: object
          example: { custify: "1234" }
        company:
          description: Custify's internal ID of the company for which the financial deal is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        people:
          description: Custify's internal ID of the people for which the financial deal is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        name:
          description: The name of the financial deal.
          type: string
          example: "deal01"
        status:
          description: The status of the financial deal.
          type: string
          example: "won"
        value:
          description: The value of the financial deal.
          type: integer
          example: 199
        addedAt:
          description: The date the financial deal was added.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        wonAt:
          description: The date the financial deal was won.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        lostAt:
          description: The date the financial deal was lost.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        metadata:
          description: An object that contains some extra information.
          type: object
    FinancialInvoice:
      type: object
      required:
        - externalId
      properties:
        externalId:
          description: Your internal ID of the financial invoice.
          type: string
          example: "invoice01"
        company:
          description: Custify's internal ID of the company for which the financial invoice is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        company_id:
          description: Your internal identifier of the company
          type: string
          example: "20"
        people:
          description: Custify's internal ID of the people for which the financial invoice is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        user_id:
          description: Your internal identifier of the people
          type: string
          example: "20"
        status:
          description: The status of the financial invoice.
          type: string
          example: "unpaid"
        invoicedAt:
          description: The date the financial invoice.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        paidAt:
          description: The date the financial invoice was paid.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        total:
          description: The total the financial invoice.
          format: integer
          example: 200
        amountPaid:
          description: The total amount paid for the financial invoice.
          format: integer
          example: 50
    FinancialInvoiceListing:
      type: object
      properties:
        externalIds:
          description: An object containing details about sources from where the invoice came. In this object is saved the `externalId` you send.
          type: object
          example: { custify: "1234" }
        company:
          description: Custify's internal ID of the company for which the financial invoice is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        people:
          description: Custify's internal ID of the people for which the financial invoice is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        status:
          description: The status of the financial invoice.
          type: string
          example: "unpaid"
        invoicedAt:
          description: The date the financial invoice.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        paidAt:
          description: The date the financial invoice was paid.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        total:
          description: The total the financial invoice.
          format: integer
          example: 200
        amountPaid:
          description: The total amount paid for the financial invoice.
          format: integer
          example: 50
        metadata:
          description: An object that contains some extra information.
          type: object
    FinancialSubscription:
      type: object
      required:
        - externalId
      properties:
        externalId:
          description: Your internal ID of the financial subscription.
          type: string
          example: "invoice01"
        company:
          description: Custify's internal ID of the company for which the financial subscription is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        company_id:
          description: Your internal identifier of the company
          type: string
          example: "20"
        people:
          description: Custify's internal ID of the people for which the financial subscription is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        user_id:
          description: Your internal identifier of the people
          type: string
          example: "20"
        mrr:
          description: The MRR for the financial subscription.
          format: integer
          example: 200
        dueInvoicesCount:
          description: The number of due invoices.
          type: integer
          example: 1
        dueInvoicesTotal:
          description: The sum of due invoices.
          type: integer
          example: 200
        dueInvoicesSince:
          description: The oldest date of the due invoice.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        paidInvoicesCount:
          description: The number of paid invoices.
          type: integer
          example: 10
        paidInvoicesTotal:
          description: The sum of paid invoices.
          type: integer
          example: 2000
        lastInvoiceStatus:
          description: The status of the last invoice.
          type: string
          example: "unpaid"
        lastTransactionStatus:
          description: The status of the last transaction.
          type: string
          example: "failed"
        billingPeriod:
          description: The billing period.
          type: integer
          example: 1
        billingPeriodUnit:
          description: The billing period unit.
          type: string
          example: "month"
        startedAt:
          description: The date the subscription started.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        currentCycleStartAt:
          description: The date the current cycle of the subscription starts.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        currentCycleEndAt:
          description: The date the current cycle of the subscription ends.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        nextBillingAt:
          description: The date the next billing for the subscription.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        canceledAt:
          description: The date the subscription was cancelled.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        plan:
          description: The plan for the subscription.
          type: string
          example: "Platinum"
        metadata:
          description: An object that contains some extra information.
          type: object
    FinancialSubscriptionListing:
      type: object
      properties:
        externalIds:
          description: An object containing details about sources from where the invoice came. In this object is saved the `externalId` you send.
          type: object
          example: { custify: "1234" }
        company:
          description: Custify's internal ID of the company for which the financial invoice is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        people:
          description: Custify's internal ID of the people for which the financial invoice is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        mrr:
          description: The MRR for the financial subscription.
          format: integer
          example: 200
        dueInvoicesCount:
          description: The number of due invoices.
          type: integer
          example: 1
        dueInvoicesTotal:
          description: The sum of due invoices.
          type: integer
          example: 200
        dueInvoicesSince:
          description: The oldest date of the due invoice.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        paidInvoicesCount:
          description: The number of paid invoices.
          type: integer
          example: 10
        paidInvoicesTotal:
          description: The sum of paid invoices.
          type: integer
          example: 2000
        lastInvoiceStatus:
          description: The status of the last invoice.
          type: string
          example: "unpaid"
        lastTransactionStatus:
          description: The status of the last transaction.
          type: string
          example: "failed"
        billingPeriod:
          description: The billing period.
          type: integer
          example: 1
        billingPeriodUnit:
          description: The billing period unit.
          type: string
          example: "month"
        startedAt:
          description: The date the subscription started.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        currentCycleStartAt:
          description: The date the current cycle of the subscription starts.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        currentCycleEndAt:
          description: The date the current cycle of the subscription ends.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        nextBillingAt:
          description: The date the next billing for the subscription.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        canceledAt:
          description: The date the subscription was cancelled.
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        plan:
          description: The plan for the subscription.
          type: string
          example: "Platinum"
        metadata:
          description: An object that contains some extra information.
          type: object
    File:
      type: object
      required:
        - file
      properties:
        companyId:
          description: The Custify internal ID of the company
          type: string
          example: "5ea93252e0263c08145d6944"
        peopleId:
          description: The Custify internal ID of the people
          type: string
          example: "5ea93252e0263c08145d6944"
        file:
          description: The file to be uploaded
          type: string
          format: binary
    FileUploadListing:
      type: object
      required:
        - id
        - account
        - extension
        - mimeType
        - name
        - size
        - created_at
        - showInPortal
      properties:
        id:
          description: Custify's internal ID of the file
          type: string
          example: "5ea93252e0263c08145d6945"
        account:
          description: Custify's internal ID of the account
          type: string
          example: "5ea93252e0263c08145d6946"
        companies:
          description: An array of the companies the file belongs to
          type: array
          example: [ "5ea93252e0263c08145d6947" ]
        peoples:
          description: An array of the people the file belongs to
          type: array
          example: [ "5ea93252e0263c08145d6948" ]
        extension:
          description: The extension of the file
          type: string
          example: "pdf"
        mimeType:
          description: The mime type of the file
          type: string
          example: "application/pdf"
        name:
          description: The name of the file
          type: string
          example: "Document.pdf"
        size:
          description: The size of the file
          type: integer
          example: 1447260
        created_at:
          description: The date the file was uploaded in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
        showInPortal:
          description: Enable/Disable the file to be shown in the portal
          type: boolean
          example: true
    FilesListing:
      type: object
      required:
        - total
        - files
      properties:
        total:
          description: Total number of files
          type: integer
          example: 15
        files:
          description: An array of file objects that are linked to the specified entity
          type: array
          items:
            $ref: '#/components/schemas/FileUploadListing'
    SurveysListing:
      type: array
      items:
        $ref: '#/components/schemas/SurveyListing'
    SurveyListing:
      type: object
      required:
        - id
      properties:
        id:
          description: The Custify internal ID of the survey
          type: string
          example: "5ea93252e0263c08145d6948"
        name:
          description: The name of the survey
          type: string
          example: "Follow-up survey"
        type:
          description: The type of the survey
          type: string
          enum:
            - nps
            - csat
          example: "nps"
        created_at:
          description: The date the survey was created in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
    SurveyResponsesResult:
      type: object
      required:
        - responses
        - total
        - page
        - itemsPerPage
      properties:
        responses:
          description: An array of survey response objects
          type: array
          items:
            $ref: '#/components/schemas/SurveyResponse'
        total:
          description: Total number of responses for this survey
          type: integer
          example: 142
        page:
          description: Current page number
          type: integer
          example: 1
        itemsPerPage:
          description: Number of items per page
          type: integer
          example: 20
    SurveyResponse:
      type: object
      required:
        - id
        - score
        - responseDate
      properties:
        id:
          description: The Custify internal ID of the survey response
          type: string
          example: "5ea93252e0263c08145d6948"
        email:
          description: The email address of the respondent
          type: string
          example: "john.doe@mail.com"
        name:
          description: The name of the respondent
          type: string
          example: "John Doe"
        people:
          description: The ID of the person associated with the survey response
          type: string
          example: "5ea93252e0263c08145d6948"
        company:
          description: The ID of the company associated with the survey response
          type: string
          example: "5ea93252e0263c08145d6948"
        score:
          description: The score given by the respondent. For NPS surveys the score ranges from 0 to 10. For CSAT surveys the score ranges from 1 to 5.
          type: integer
          example: 9
        comment:
          description: The optional comment left by the respondent
          type: string
          example: "Great product, very easy to use!"
        responseDate:
          description: The date and time when the response was submitted
          type: string
          format: date-time
          example: "2024-03-15T14:30:00.000Z"
        extraQuestions:
          description: Answers to any additional questions configured in the survey
          type: array
          items:
            type: object
            properties:
              question:
                description: The extra question text
                type: string
                example: "What feature do you value the most?"
              answer:
                description: The answer provided (can be a string, number, boolean or array of strings)
                example: "Dashboard analytics"
    TimeTrackListing:
      type: object
      required:
        - id
        - name
        - duration
        - startDate
      properties:
        id:
          description: The Custify internal ID of the time tracking
          type: string
          example: "5ea93252e0263c08145d6948"
        name:
          description: The name of the time tracking
          type: string
          example: "First time tracking"
        duration:
          description: The duration in seconds of the time tracking
          type: integer
          example: 3600
        startDate:
          description: The date the time tracking was started
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        tags:
          description: An array of the tags to apply to the time tracking. Valid tag IDs are Custify internal IDs tags having category `time_tracker`
          type: array
          items:
            $ref: '#/components/schemas/TagsList'
        company:
          description: An array of the companies the time tracking belongs to
          type: array
          example: [ "5ea93252e0263c08145d6947" ]
        people:
          description: An array of the people the time tracking belongs to
          type: array
          example: [ "5ea93252e0263c08145d6948" ]
        user:
          description: The Custify internal ID of the user who created (or for whom) the time tracking is created
          type: string
          example: "5ea93252e0263c08145d6948"
        created_at:
          description: The date the time tracking was created in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
        updated_at:
          description: The date the time tracking was updated in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
    TimeTrack:
      type: object
      required:
        - duration
        - name
        - startedDate
      properties:
        company:
          description: Custify's internal ID of the company for which the time tracking is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        people:
          description: Custify's internal ID of the people for which the time tracking is created/updated
          type: string
          example: "5ea93252e0263c08145d6944"
        duration:
          description: The duration in seconds of the time tracking
          type: integer
          example: 3600
        name:
          description: The name of the time tracking
          type: string
          example: "First time tracking"
        startedDate:
          description: The date the time tracking was started
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        tags:
          description: An array of the tags to apply to the time tracking. Valid tag IDs are Custify internal IDs tags having category `time_tracker`
          type: array
          items:
            $ref: '#/components/schemas/TagsList'
    Meeting:
      type: object
      properties:
        user_id:
          description: Your internal ID of the person to associate the meeting with. Required if `email` and `company_id` are not provided.
          type: string
          example: "user-123"
        email:
          description: The email of the person to associate the meeting with. Alternative to `user_id`.
          type: string
          example: "john.doe@acme.com"
        company_id:
          description: Your internal ID of the company to associate the meeting with. Required if `user_id` and `email` are not provided.
          type: string
          example: "acme-corp"
        id:
          description: The Custify internal ID of the meeting. If provided, the matching meeting will be updated.
          type: string
          example: "5ea93252e0263c08145d6948"
        externalId:
          description: Your external ID for the meeting. Used for upsert — if found, the meeting is updated; otherwise created.
          type: string
          example: "meeting-ext-001"
        title:
          description: The title of the meeting.
          type: string
          example: "Quarterly Business Review"
        description:
          description: The description of the meeting.
          type: string
          example: "Q3 review with the customer."
        startAt:
          description: The start date and time of the meeting (ISO 8601 format).
          type: string
          format: date-time
          example: "2024-09-01T10:00:00.000Z"
        endAt:
          description: The end date and time of the meeting (ISO 8601 format). Used together with `startAt` to calculate `duration`.
          type: string
          format: date-time
          example: "2024-09-01T11:00:00.000Z"
        location:
          description: The location or URL of the meeting.
          type: string
          example: "https://meet.example.com/qbr"
        direction:
          description: The direction of the meeting.
          type: string
          enum:
            - incoming
            - outgoing
          example: "outgoing"
        recurring:
          description: Whether the meeting is recurring.
          type: boolean
          example: false
        organizer:
          description: The organizer of the meeting.
          type: object
          properties:
            name:
              description: The name of the organizer.
              type: string
              example: "Jane Smith"
            email:
              description: The email of the organizer.
              type: string
              example: "jane.smith@yourcompany.com"
        participants:
          description: An array of participants in the meeting.
          type: array
          items:
            type: object
            properties:
              name:
                description: The name of the participant.
                type: string
                example: "John Doe"
              email:
                description: The email of the participant.
                type: string
                example: "john.doe@acme.com"
              status:
                description: The RSVP status of the participant.
                type: string
                enum:
                  - pending
                  - accepted
                  - rejected
                  - maybe
                example: "accepted"
              organizer:
                description: Whether this participant is the organizer.
                type: boolean
                example: false
              optional:
                description: Whether this participant is optional.
                type: boolean
                example: false
        tags:
          description: An array of tag IDs to apply to the meeting. Valid tag IDs are Custify internal IDs of tags with category `meeting`.
          type: array
          items:
            $ref: '#/components/schemas/TagsList'
    MeetingsListing:
      type: object
      required:
        - id
      properties:
        id:
          description: The Custify internal ID of the meeting
          type: string
          example: "5ea93252e0263c08145d6948"
        title:
          description: The title of the meeting
          type: string
          example: "First meeting"
        tags:
          description: An array of the tags to apply to the meeting. Valid tag IDs are Custify internal IDs tags having category `meeting`
          type: array
          items:
            $ref: '#/components/schemas/TagsList'
        startAt:
          description: The start date of the meeting
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        endAt:
          description: The end date of the meeting
          format: date-time
          example: "2022-04-01T12:00:00.000Z"
        duration:
          description: The duration in seconds of the meeting
          type: integer
          example: 3600
        recurring:
          description: Whether the meeting is recurring
          type: boolean
          example: true
        created_at:
          description: The date the meeting was created in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
        updated_at:
          description: The date the meeting was updated in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
        company:
          description: An array of the companies the meeting belongs to
          type: array
          example: ["5ea93252e0263c08145d6944", "5ea93252e0263c08145d6945"]
        people:
          description: An array of the people the meeting belongs to
          type: array
          example: ["5ea93252e0263c08145d6946", "5ea93252e0263c08145d6947"]
        organizer:
          description: An object with the user who is the organizer of the meeting
          type: object
          properties:
            name:
              description: The name of the user
              type: string
              example: "John Doe Sr."
            email:
              description: The email of the user
              type: string
              example: "johndoe@me.com"
            people:
              description: The Custify internal ID of the user
              type: string
              example: "5ea93252e0263c08145d6946"
        participants:
          description: An array of objects with the participants of the meeting
          type: array
          items:
            type: object
            properties:
              name:
                description: The name of the user
                type: string
                example: "John Doe Sr."
              email:
                description: The email of the user
                type: string
                example: "johndoe@me.com"
              people:
                description: The Custify internal ID of the user
                type: string
                example: "5ea93252e0263c08145d6946"
              status:
                description: The status of the participant in the meeting
                type: string
                example: "accepted"
              comment:
                description: The comment of the participant in the meeting
                type: string
                example: "I'm here"
              organizer:
                description: Whether the participant is the organizer of the meeting
                type: boolean
                example: true
              optional:
                description: Whether the participant is optional
                type: boolean
                example: true
    CalculatedMetricsListing:
      type: object
      required:
        - id
      properties:
        id:
          description: The Custify internal ID of the calculated metric
          type: string
          example: "5ea93252e0263c08145d6948"
        name:
          description: The name of the calculated metric
          type: string
          example: "First calculated metric"
        description:
          description: The description of the calculated metric
          type: string
          example: "This is the first calculated metric"
        type:
          description: The type of the calculated metric (company or people)
          type: string
          example: "company"
        tags:
          description: An array of the tags to apply to the calculated metric. Valid tag IDs are Custify internal IDs tags having category `calculated_metric`
          type: array
          items:
            $ref: '#/components/schemas/TagsList'
        frequency:
          description: The frequency of the calculated metric (number of hours)
          type: number
          example: 12
        created_at:
          description: The date the calculated metric was created in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
        updated_at:
          description: The date the calculated metric was updated in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
    HealthScoreListing:
      type: object
      required:
        - id
      properties:
        id:
          description: The Custify internal ID of the health score
          type: string
          example: "5ea93252e0263c08145d6948"
        name:
          description: The name of the health score
          type: string
          example: "First health score"
        description:
          description: The description of the health score
          type: string
          example: "This is the first health score"
        tags:
          description: An array of the tags to apply to the health score. Valid tag IDs are Custify internal IDs tags having category `health_score`
          type: array
          items:
            $ref: '#/components/schemas/TagsList'
        kpiType:
          description: The type of the kpi used to calculate the health score
          type: string
          example: "event"
        globalHealthScoreImpact:
          description: The global health score impact (low, medium, high)
          type: string
          example: "high"
        created_at:
          description: The date the health score was created in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
        updated_at:
          description: The date the health score was updated in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
    SegmentsListing:
      type: object
      required:
        - id
      properties:
        id:
          description: The Custify internal ID of the segment
          type: string
          example: "5ea93252e0263c08145d6948"
        name:
          description: The name of the segment
          type: string
          example: "First segment"
        goal:
          description: The description of the segment
          type: string
          example: "This is the first segment"
        tags:
          description: An array of the tags to apply to the segment. Valid tag IDs are Custify internal IDs tags having category `segment`
          type: array
          items:
            $ref: '#/components/schemas/TagsList'
        type:
          description: The type of the segment (company or people)
          type: string
          example: "people"
        created_at:
          description: The date the segment was created in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
        updated_at:
          description: The date the segment was updated in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
    LifecycleListing:
      type: object
      required:
        - id
        - name
      properties:
        id:
          description: The Custify internal ID of the lifecycle
          type: string
          example: "5ea93252e0263c08145d6948"
        name:
          description: The name of the lifecycle
          type: string
          example: "Onboarding lifecycle"
        description:
          description: The description of the lifecycle
          type: string
          example: "Customer onboarding process"
        startCondition:
          description: The start condition of the lifecycle
          type: string
          enum: [manually started, enters segment, leaves segment, is in segment, another lifecycle finishes, custom condition]
          example: "enters segment"
        startConditionEntityName:
          description: The name of the entity associated with the start condition
          type: string
          example: "New customers"
        endCondition:
          description: The end condition of the lifecycle
          type: string
          enum: [all goals are reached, manually completed, enters segment, leaves segment, all tasks are done, all goals and all tasks are completed, custom condition]
          example: "all goals are reached"
        endConditionEntityName:
          description: The name of the entity associated with the end condition
          type: string
          example: "Onboarded customers"
        daysToComplete:
          description: Number of days to complete the lifecycle
          type: string
          example: "30"
        daysToStuck:
          description: Number of days until lifecycle is considered stuck
          type: string
          example: "7"
        position:
          description: The position of the lifecycle in the list
          type: number
          example: 1
        status:
          description: The status of the lifecycle (active or inactive)
          type: string
          enum: [active, inactive]
          example: "active"
        showInC360:
          description: Whether the lifecycle is shown in Company 360
          type: boolean
          example: true
        tags:
          description: An array of tag IDs associated with the lifecycle
          type: array
          items:
            type: string
          example: ["5d11d5687113bc33f07573f0"]
        goals:
          description: An array of lifecycle goals
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: "5ea93252e0263c08145d6949"
              name:
                type: string
                example: "Complete profile"
              criteria:
                type: string
                example: "profile_completed"
              segment:
                type: string
                example: "5ea93252e0263c08145d694a"
        tasks:
          description: An array of task templates associated with the lifecycle
          type: array
          items:
            type: object
        settings:
          description: Additional settings for the lifecycle
          type: object
        created_by:
          description: The Custify internal ID of the user who created the lifecycle
          type: string
          example: "619614c208f44122f75dfea2"
        created_by_name:
          description: The name of the user who created the lifecycle
          type: string
          example: "John Doe"
        updated_by:
          description: The Custify internal ID of the user who last updated the lifecycle
          type: string
          example: "619614c208f44122f75dfea2"
        updated_by_name:
          description: The name of the user who last updated the lifecycle
          type: string
          example: "John Doe"
        created_at:
          description: The date the lifecycle was created in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
        updated_at:
          description: The date the lifecycle was updated in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
    PlaybookListing:
      type: object
      required:
        - id
        - name
      properties:
        id:
          description: The Custify internal ID of the playbook
          type: string
          example: "5ea93252e0263c08145d6948"
        name:
          description: The name of the playbook
          type: string
          example: "Welcome playbook"
        description:
          description: The description of the playbook
          type: string
          example: "Automated welcome sequence for new customers"
        type:
          description: The type of the playbook (companies or people)
          type: string
          enum: [companies, people]
          example: "companies"
        position:
          description: The position of the playbook in the list
          type: number
          example: 1
        status:
          description: The status of the playbook (active or inactive)
          type: string
          enum: [active, inactive]
          example: "active"
        company_counts:
          description: Company counts for the playbook (if includeCounts=true)
          type: object
          properties:
            in_progress:
              type: number
              example: 15
            completed:
              type: number
              example: 45
            completed_end:
              type: number
              example: 30
            completed_manual:
              type: number
              example: 10
            completed_exit:
              type: number
              example: 5
        tags:
          description: An array of tag IDs associated with the playbook
          type: array
          items:
            type: string
          example: ["5d11d5687113bc33f07573f0"]
        settings:
          description: Additional settings for the playbook
          type: object
        created_at:
          description: The date the playbook was created in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
        updated_at:
          description: The date the playbook was updated in Custify
          format: date-time
          example: "2022-10-01T12:00:00.000Z"
    ObjectiveListing:
      type: object
      required:
        - id
        - name
      properties:
        id:
          description: The Custify internal ID of the objective
          type: string
          example: "5ea93252e0263c08145d6948"
        name:
          description: The name of the objective
          type: string
          example: "Increase product adoption"
        description:
          description: The description of the objective
          type: string
          example: "Ensure the customer adopts all core features within 90 days"
        importance:
          description: The importance level of the objective
          type: string
          enum:
            - low
            - medium
            - high
          example: "high"
        risk:
          description: The risk level of the objective
          type: string
          enum:
            - low
            - medium
            - high
          example: "medium"
        health:
          description: The health rating of the objective (0 to 5)
          type: number
          example: 4
        completionPercentage:
          description: The completion percentage of the objective (0 to 100)
          type: number
          example: 65
        completionType:
          description: How the completion percentage is calculated
          type: string
          enum:
            - manual
            - attribute_based
          example: "manual"
        completionAttribute:
          description: The company attribute used for automatic completion calculation (only when completionType is attribute_based)
          type: string
          example: "custom_attributes.onboarding_score"
        valueBaseline:
          description: The baseline value for attribute-based completion tracking
          type: string
          example: "0"
        valueTarget:
          description: The target value for attribute-based completion tracking
          type: string
          example: "100"
        valueCurrent:
          description: The current value for attribute-based completion tracking
          type: string
          example: "65"
        objectiveStatus:
          description: The current status of the objective
          type: string
          enum:
            - not_started
            - in_progress
            - paused
            - archived
            - abandoned
            - completed
          example: "in_progress"
        startAt:
          description: The start date of the objective
          type: string
          format: date-time
          example: "2024-01-15T00:00:00.000Z"
        dueAt:
          description: The due date of the objective
          type: string
          format: date-time
          example: "2024-06-30T00:00:00.000Z"
        completedAt:
          description: The date the objective was completed
          type: string
          format: date-time
          example: "2024-05-20T10:30:00.000Z"
        tags:
          description: An array of tag IDs associated with the objective
          type: array
          items:
            type: string
          example: ["5ea93252e0263c08145d6948"]
        company:
          description: The Custify internal ID of the company this objective belongs to
          type: string
          example: "5fa0366f7ebb2b60c9f4dc03"
        assignedTo:
          description: |
            The ID of the entity assigned to this objective. The value depends on the assignment type:
            - If assigned to a User (internal team member): Contains the User ID from Custify
            - If assigned to a Customer (person/contact): Contains the Customer ID from Custify
            - If assigned to Customer but no specific person is selected: Contains the string "Customer"
          type: string
          example: "5ea93252e0263c08145d6950"
        assignedToName:
          description: |
            The name of the entity assigned to this objective. The value depends on the assignment type:
            - If assigned to a User: Contains the User's name from Custify
            - If assigned to a Customer: Contains the Customer's name from Custify
            - If assigned to Customer but no specific person is selected: null
          type: string
          nullable: true
          example: "John Smith"
        collaborators:
          description: |
            An array of collaborators on this objective. Each collaborator has a name and entity ID.
            Collaborators can be Users (internal team members), Customers (people/contacts), or External collaborators.
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: The name of the collaborator
                example: "Jane Doe"
              entity:
                type: string
                description: The Custify internal ID of the collaborator entity
                example: "5ea93252e0263c08145d6951"
          example:
            - name: "Collaborator 1"
              entity: "66152404f5a78cb0a2512127"
            - name: "Collaborator 2"
              entity: "655cb9430a400bc0eac7633b"
        created_at:
          description: The date the objective was created in Custify
          type: string
          format: date-time
          example: "2024-01-10T12:00:00.000Z"
        updated_at:
          description: The date the objective was last updated in Custify
          type: string
          format: date-time
          example: "2024-03-15T14:30:00.000Z"
    FileUnlink:
      type: object
      required:
        - fileId
      properties:
        fileId:
          description: The Custify internal ID of the file
          type: string
          example: "5ea93252e0263c08145d6948"
        companyId:
          description: The Custify internal ID of the company
          type: string
          example: "5ea93252e0263c08145d6949"
        peopleId:
          description: The Custify internal ID of the people
          type: string
          example: "5ea93252e0263c08145d694a"
    FileShowInPortal:
      type: object
      required:
        - showInPortal
      properties:
        showInPortal:
          description: Enable/Disable the file to be shown in the portal
          type: boolean
          example: true
    Message:
      type: object
      required:
        - message
      properties:
        message:
          description: Message response
          type: string
          example: "message"
    FileList:
      type: string
      example: "5d11d5687113bc33f07573f0"
security:
  - BearerAUTH: [ ]
