### API Key Authentication Example

Source: https://developer.cloze.com/

Include the API key in a query parameter named `api_key` for authentication.

```http
GET https://api.cloze.com/v1/user/profile?api_key=123
```

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

### API Key as Bearer Token Example

Source: https://developer.cloze.com/

Alternatively, provide the API key as a bearer token in the `Authorization` header.

```http
GET https://api.cloze.com/v1/user/profile
Authorization: Bearer ${api_key}
```

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

### Get project segments

Source: https://developer.cloze.com/swagger.json

Retrieves the project segments available within a Cloze user account.

```APIDOC
## GET /v1/user/segments/projects

### Description
Get the project segments available within a cloze user account..

### Method
GET

### Endpoint
/v1/user/segments/projects

### Parameters

### Request Example

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success
- **message** (string) - If an error occurs, this is the human readable description
- **list** (array) - An array of segment objects
  - **name** (string) - user label for segment
  - **key** (string) - internal segment name

#### Response Example
{
  "errorcode": 0,
  "list": [
    {
      "name": "Potential",
      "key": "future"
    },
    {
      "name": "Active",
      "key": "current"
    },
    {
      "name": "Done",
      "key": "won"
    },
    {
      "name": "Lost",
      "key": "lost"
    }
  ]
}
```

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

### Get Steps

Source: https://developer.cloze.com/swagger.json

Retrieves the steps available for a Cloze user account, categorized by segments and stages. This endpoint can be filtered by segment and/or stage using query parameters.

```APIDOC
## GET /v1/user/steps

### Description
For segments, and stages within each segment, retrieve the steps available for a cloze user account.
Optional query parameters may constrain the results by segment, or by segment and stage.
Steps are returned as user labels and in Cloze internal step name format.

### Method
GET

### Endpoint
/v1/user/steps

### Parameters
#### Query Parameters
- **segment** (string) - optional segment name
- **stage** (string) - optional stage name, requires segment parameter to be provided if set

### Request Example

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success
- **message** (string) - If an error occurs, this is the human readable description
- **list** (array) - A list of steps
  - **name** (string) - user label for step
  - **key** (string) - internal step name

#### Response Example
{
  "errorcode": 0,
  "list": [
    {
      "name": "Lead",
      "key": "lead"
    },
    {
      "name": "Contact",
      "key": "contact"
    },
    {
      "name": "Opportunity",
      "key": "opportunity"
    },
    {
      "name": "Customer",
      "key": "customer"
    }
  ]
}
```

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

### Get Similar Projects

Source: https://developer.cloze.com/swagger.json

Given a project, find ones that are similar. This endpoint allows specifying a unique project ID and an optional limit for the number of similar projects to return.

```APIDOC
## POST /v1/projects/similar

### Description
Given a project, find ones that are similar.

### Method
POST

### Endpoint
/v1/projects/similar

### Parameters
#### Request Body
- **details** (object) - Required - Details of the project to find similar ones for.
  - **uniqueid** (string) - Required - Unique Id of the project to get similar ones for (e.g. syncKey, portableId, app link, etc.).
  - **limit** (integer) - Optional - Maximum number of matches to return (1 to 25).
  - **stages** (array) - Optional - Only include projects in these stages in the results. Allowed values: "future", "current", "pending", "won", "lost".
  - **team** (string) - Optional - Filter by team.
```

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

### Get User Keywords

Source: https://developer.cloze.com/swagger.json

Retrieves a list of tags associated with the user. These tags can be used for filtering or categorization.

```APIDOC
## GET /v1/user/keywords

### Description
Retrieves a list of tags associated with the user. These tags can be used for filtering or categorization.

### Method
GET

### Endpoint
/v1/user/keywords

### Parameters

### Request Example

### Response
#### Success Response (200)
- **people** (object) - Information about the views that are defined for people
  - **label** (object) - Labels used for one or more people views
    - **singular** (string) - End-user visible label used for one view
    - **plural** (string) - End-user visible label used for multiple views
  - **views** (array) - Array of views that apply to people
    - **id** (string) - id of this view
    - **name** (string) - name of this view
- **companies** (object) - Information about the views that are defined for companies
  - **label** (object) - Labels used for one or more company views
    - **singular** (string) - End-user visible label used for one view
    - **plural** (string) - End-user visible label used for multiple views
  - **views** (array) - Array of views that apply to companies
    - **id** (string) - id of this view
    - **name** (string) - name of this view
- **projects** (object) - Information about the views that are defined for projects
  - **label** (object) - Labels used for one or more project views
    - **singular** (string) - End-user visible label used for one view
    - **plural** (string) - End-user visible label used for multiple views
  - **views** (array) - Array of views that apply to projects
    - **id** (string) - id of this view
    - **name** (string) - name of this view

#### Response Example
{
  "people": {
    "label": {
      "singular": "Audience",
      "plural": "Audiences"
    },
    "views": [
      {
        "id": "my",
        "name": "My People"
      },
      {
        "id": "focus",
        "name": "My Network"
      }
    ]
  },
  "companies": {
    "label": {
      "singular": "View",
      "plural": "Views"
    },
    "views": [
      {
        "id": "my",
        "name": "My Companies"
      },
      {
        "id": "focus",
        "name": "My Focus"
      }
    ]
  },
  "projects": {
    "label": {
      "singular": "View",
      "plural": "Views"
    },
    "views": [
      {
        "id": "my",
        "name": "My Properties"
      },
      {
        "id": "focus",
        "name": "My Focus"
      }
    ]
  }
}
```

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

### Get Projects

Source: https://developer.cloze.com/swagger.json

Retrieves a list of projects based on specified criteria. Supports filtering by stage, segment, and custom fields, with options for sorting and formatting.

```APIDOC
## GET /v1/projects

### Description
Retrieves a list of projects. Supports filtering by stage, segment, and custom fields, with options for sorting and formatting.

### Method
GET

### Endpoint
/v1/projects

### Parameters
#### Query Parameters
- **stage** (string) - Optional - Filter projects by stage.
- **segment** (string) - Optional - Filter projects by segment.
- **freeformquery** (string) - Optional - Freeform search for projects.
- **keysonly** (boolean) - Optional - Return only the keys of the projects.
- **pagesize** (integer) - Optional - Number of projects to return per page.
- **sort** (string) - Optional - Sort order for the projects. Possible values: lastchanged, bestrelationship, firstmet, lasttalked, wentquiet, assigned, duenext, duepast, first, last, nextstep, distance, value, created, start, end, name.
- **sortdir** (string) - Optional - Sort direction. Possible values: asc, dec.
- **format** (boolean) - Optional - Return formatted names and values for custom fields.
- **team** (string) - Optional - Filter projects by team.
- **local** (boolean) - Optional - Identifies whether the team relation or local relation is to be retrieved or deleted.

### Responses
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success.
- **projects** (array) - List of project references.
```

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

### Get Project Timeline

Source: https://developer.cloze.com/swagger.json

Retrieves the keys of messages within a project's timeline. This operation requires a query object specifying the timeline details.

```APIDOC
## POST /v1/projects/timeline

### Description
Get the keys of the messages in the project's timeline.

### Method
POST

### Endpoint
/v1/projects/timeline

### Parameters
#### Request Body
- **query** (object) - The query object, typically referencing a TimelineQuery schema.

### Response
#### Success Response (200)
- Response object conforming to the TimelineQueryResponse schema.
```

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

### GET /v1/projects/get

Source: https://developer.cloze.com/swagger.json

Retrieves a specific project using its unique identifier. Supports various identifiers like Twitter handle, email, or direct ID, and allows for detailed or formatted responses.

```APIDOC
## GET /v1/projects/get

### Description
Get project based on a unique identifier, for example, twitter, email address or direct identifier.

### Method
GET

### Endpoint
/v1/projects/get

### Parameters
#### Query Parameters
- **projectuniqueid** (string) - Required - The unique identifier of the project.
- **team** (boolean) - Optional - Identifies whether the team relation or local relation is to be retrieved.
- **queryformat** (string) - Optional - The format for the query, e.g., 'json'.
- **detailed** (boolean) - Optional - If true, returns detailed project information.

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success.
- **project** (object) - The project object, referencing ProjectRef definition.
```

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

### Get Project Stages

Source: https://developer.cloze.com/swagger.json

Retrieves the Cloze stages applicable to projects. This endpoint returns both the internal Cloze project stage keys and their corresponding user-defined custom labels.

```APIDOC
## GET /v1/user/stages/projects

### Description
Get the Cloze stages that apply to projects. Returns the internal Cloze project stage
keys along with their user custom label.

### Method
GET

### Endpoint
/v1/user/stages/projects

### Parameters
None

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success.
- **message** (string) - If an error occurs, this is the human readable description.
```

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

### Get Tags

Source: https://developer.cloze.com/swagger.json

Retrieves the set of tags that apply to people, companies, or projects. You can filter by type and limit the number of results.

```APIDOC
## GET /v1/tags

### Description
Get the set of tags that apply to people, companies, or projects.

### Method
GET

### Endpoint
/v1/tags

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of tags to return. Defaults to 100.
- **type** (string) - Optional - Get the tags for this type of relation. Allowed values: "person", "company", "project". Defaults to "person".

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success.
- **message** (string) - If an error occurs, this is the human readable description.
- **keywords** (array) - Array of tags.
  - **id** (string) - tag id (without the hash sign)
  - **count** (integer) - number of relations this keyword applies to

### Response Example
```json
{
  "errorcode": 0,
  "keywords": [
    {
      "id": "dog-lover",
      "count": 27
    },
    {
      "id": "garden-club",
      "count": 23
    }
  ]
}
```
```

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

### Get User Views

Source: https://developer.cloze.com/swagger.json

Retrieves the set of views and audiences that apply to people, companies, and projects. Audiences and views are equivalent concepts, with 'audience' used for people and 'view' for companies and projects.

```APIDOC
## GET /v1/user/views

### Description
Get the set of views and audiences that apply to people, companies, and projects. Under the covers audiences and views are equivalent, but the term audience is used for people and view for companies and projects.

### Method
GET

### Endpoint
/v1/user/views

### Parameters

### Request Example
(No request body or parameters specified in the source)

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success
- **message** (string) - If an error occurs, this is the human readable description
- **people** (object) - Information about the audiences that are defined for people
  - **label** (object) - Labels used for one or more people audiences
    - **singular** (string) - End-user visible label used for one view
    - **plural** (string) - End-user visible label used for multiple views
  - **views** (array) - Array of views that apply to people
    - **id** (string) - id of this view
    - **name** (string) - name of this view

#### Response Example
(No response example provided in the source)
```

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

### Get contact stages

Source: https://developer.cloze.com/swagger.json

Retrieves the Cloze stages applicable to people and company contacts. This includes both the internal Cloze stage keys and their user-defined labels.

```APIDOC
## GET /v1/user/stages/people

### Description
Get the Cloze stages that apply to people and company contacts. Returns the internal Cloze stage
keys along with their user custom label.

### Method
GET

### Endpoint
/v1/user/stages/people

### Parameters

### Request Example

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success
- **message** (string) - If an error occurs, this is the human readable description
- **list** (array) - An array of stage objects
  - **name** (string) - user label for stage
  - **key** (string) - internal stage name

#### Response Example
{
  "errorcode": 0,
  "list": [
    {
      "name": "Lead",
      "key": "lead"
    },
    {
      "name": "Lost",
      "key": "out"
    },
    {
      "name": "Potential",
      "key": "future"
    },
    {
      "name": "Active",
      "key": "current"
    },
    {
      "name": "Inctive",
      "key": "past"
    }
  ]
}
```

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

### Query Project Data

Source: https://developer.cloze.com/swagger.json

Query for data about projects/deals that are active or in the pipeline. You can select projects according to where their start, active and end dates fall relative to a reporting period, and retrieve various metrics for each.

```APIDOC
## POST /v1/analytics/projects

### Description
Query for data about projects/deals that are active or in the pipeline. You can select projects according to where their start, active and end dates fall relative to a reporting period, and retrieve various metrics for each.

###Reporting Period
The `scale` property controls what type of reporting period you want to query - the current `year`, `quarter`, or `month`.<br/>
The `relative` property allows you to retrieve future periods, by setting e.g. `relative:0` for the current
period, `relative:1` for the next, and so on. If not set it defaults to `relative:0`
###Metrics
The following metrics are available about each project<br/>
`segment` - the segment the project belongs to<br/>
`stage` - the stage the project is in<br/>
`meta_value` - the financial value of the project<br/>
`project_start` - UTC ms timestamp of the project start date<br/>
`project_active` - UTC ms timestamp of the project active date<br/>
`project_end` - UTC ms timestamp of the project end date<br/>

### Method
POST

### Endpoint
/v1/analytics/projects

### Parameters
#### Request Body
- **queries** (object) - Required - Map of `ProjectQuery` definitions. The response will be organized by the query names that were provided in the input map.
  - **mode** (string) - Optional - one of `pipeline` or `active` (default is pipeline)
  - **exampleQueryName** (object) - Required - Each query in the map should have a different name. The response will be organized by the query names that were provided.
    - **always** (string) - Optional - e.g. "in-period"
    - **scale** (string) - Optional - e.g. "quarter"
    - **relative** (integer) - Optional - e.g. 0
    - **metrics** (array) - Optional - List of metrics to retrieve
      - (string) - e.g. "stage"

### Request Example
```json
{
  "queries": {
    "dealsqtr": {
      "mode": "pipeline",
      "always": "in-period",
      "scale": "quarter",
      "relative": 0,
      "metrics": [
        "stage",
        "segment",
        "nextstep",
        "meta_value",
        "project_start",
        "project_end"
      ]
    }
  }
}
```

### Response
#### Success Response (200)
- **object** (object) - Pipeline data

#### Response Example
```json
{
  "example": "response body"
}
```
```

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

### Get Projects

Source: https://developer.cloze.com/swagger.json

Retrieves projects based on unique identifiers such as app link, syncKey, or portableId. It can also return formatted names and values for custom fields, and specify whether to retrieve team or local relations.

```APIDOC
## POST /v1/projects

### Description
Get projects based on unique identifiers (for example app link, syncKey, or portableId).

### Method
POST

### Endpoint
/v1/projects

### Parameters
#### Request Body
- **ids** (array[string]) - Optional - Each is a project unique identifier - syncKey, portableId, 'direct:..', or custom identifier (e.g. na.salesforce.com:013434hfnf2). If not provided returns any companies explicitly specified in the API key or app configuration.
- **format** (boolean) - Optional - Return formatted names and values for custom fields
- **team** (boolean) - Optional - Identifies whether the team relation or local relation is to be retrieved or deleted
- **detailed** (boolean) - Optional - retrieve detailed information

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success
- **projects** (array) - Array of ProjectRef objects
```

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

### Create project

Source: https://developer.cloze.com/swagger.json

Creates a new project or merges updates into an existing one. Projects must have a name.

```APIDOC
## POST /v1/projects/create

### Description
Create a new project or merge updates into an existing one. Projects require a name.

### Method
POST

### Endpoint
/v1/projects/create

### Parameters
#### Request Body
- **project** (ProjectRef) - The project or deal to create

### Request Example
{
  "project": {
    "name": "string",
    "description": "string",
    "keywords": [
      {
        "id": "string",
        "query": "string",
        "name": "string"
      }
    ],
    "views": [
      {
        "id": "string",
        "query": "string",
        "name": "string",
        "type": "string"
      }
    ],
    "subscriptions": [
      {
        "id": "string",
        "query": "string",
        "name": "string"
      }
    ]
  }
}

### Responses
#### Success Response (200)
- **BasicResponse** - Response

#### Response Example
{
  "errorcode": 0,
  "id": "string"
}
```

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

### GET /v1/team/roles

Source: https://developer.cloze.com/swagger.json

Retrieves a list of all defined roles within a team. This requires View User and Edit Team permissions.

```APIDOC
## GET /v1/team/roles

### Description
Get a list of the defined roles in a team

Requires View User and Edit Team permissions

### Method
GET

### Endpoint
/v1/team/roles

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success
- **list** (array[TeamRole]) - a list of the names and ids for the roles
```

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

### Get Message Body

Source: https://developer.cloze.com/swagger.json

Retrieves the full body of a specific message. This should only be called when the message is being displayed to a user, as it can be an expensive operation.

```APIDOC
## POST /v1/messages/body

### Description
Get the full body of a message for display. This should only be used when the message is being displayed to a user.

### Method
POST

### Endpoint
/v1/messages/body

### Parameters
#### Request Body
- **messageInfo** (object) - Required - The key of the message
  - **key** (string) - Required - The key of the message to retrieve the body for

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success
- **mimeType** (string) - The MIME type of the message body
- **expires** (string) - The expiration date of the message body (if any)
- **lightMode** (boolean) - The message body is best rendered in light mode
- **body** (string) - The message body content

```

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

### Create a to do

Source: https://developer.cloze.com/swagger.json

Creates a new To Do item within Cloze. This endpoint allows for setting a due date, subject, participants, and assignees for the task.

```APIDOC
## POST /v1/timeline/todo/create

### Description
Create a new To Do within Cloze.

### Method
POST

### Endpoint
/v1/timeline/todo/create

### Parameters
#### Request Body
- **todo** (object) - Required - The To Do to create
  - **when** (string, number) - Optional - date stamp for reminder (1 if "someday"). Can be a string or a UTC timestamp in ms since the epoch. If not provided the To Do is treated as "someday".
  - **subject** (string) - Required - Subject or description for this To Do
  - **preview** (string) - Optional - Preview of the body (if not provided will be automatically created from the body). Must be no longer than 1kb.
  - **participants** (array of strings) - Optional - Array of people and companies related to the To Do. Each must be email addresses or other unique identifier (e.g. mobile phone numbers) for people, or domain name for company
  - **assigner** (string) - Optional - The Cloze user that is assigning the To Do This must be email addresses or other unique identifier of the user. If not provided, the assigner is the user making the request.
  - **assignee** (string) - Optional - The Cloze user this To Do is being assigned to This must be email addresses or other unique identifier of the user. If not assigned it is for the user making the request. The user must have permission to view team members and import team data to do this.
  - **dateFormat** (string) - Optional - For dates of the form 1/2/2021, this determines if they are parsed as US (month/day/year) or International (day/month/year) dates. Enum: ["us", "international"]
  - **dryrun** (boolean) - Optional - Run all validation but do not create/update the record
  - **skipImport** (boolean) - Optional - Entirely ignore the record (do not validate, create, or update the record)

### Request Example
{
  "todo": {
    "when": "2018-11-20T16:00:00Z",
    "subject": "Launch Black Friday marketing campaign",
    "participants": [
      "dave@incfire.com",
      "dana@incfire.com"
    ]
  }
}

### Response
#### Success Response (200)
- **description** (string) - Response

#### Response Example
{
  "example": "response body"
}
```

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

### List subscriptions

Source: https://developer.cloze.com/swagger.json

This method lets you list your existing webhook subscriptions.

```APIDOC
## GET /v1/webhooks

### Description
This method lets you list your subscriptions

### Method
GET

### Endpoint
/v1/webhooks

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success

(Note: The full schema for the 200 response is not fully provided in the source text, only the errorcode property is explicitly mentioned.)
```

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

### Get Person Timeline

Source: https://developer.cloze.com/swagger.json

Retrieves the keys of messages in a person's timeline. This endpoint is part of the Relations - People API.

```APIDOC
## POST /v1/people/timeline

### Description
Get the keys of the messages in the person's timeline.

### Method
POST

### Endpoint
/v1/people/timeline

### Parameters
#### Request Body
- **query** (TimelineQuery) - Description: The query

### Response
#### Success Response (200)
- **Response** (TimelineQueryResponse)

```

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

### GET /v1/companies

Source: https://developer.cloze.com/swagger.json

Retrieves a list of companies based on specified criteria. It supports filtering and formatting options for custom fields.

```APIDOC
## GET /v1/companies

### Description
Retrieves a list of companies. Supports filtering and formatting options for custom fields.

### Method
GET

### Endpoint
/v1/companies

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filter companies based on a query string.
- **queryformat** (string) - Optional - The format for the query, e.g., 'json'.
- **detailed** (boolean) - Optional - If true, returns detailed company information.
- **team** (boolean) - Optional - Identifies whether the team relation or local relation is to be retrieved.

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success.
- **companies** (array) - An array of CompanyRef objects.
```

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

### Query Parameters for People, Projects, and Companies

Source: https://developer.cloze.com/swagger.json

This section details the query parameters available for retrieving and filtering people, projects, and companies. It covers options for sorting, grouping, and specifying the scope of the query, as well as advanced filtering by modification time and free-form search.

```APIDOC
## GET /people, /projects, /companies

### Description
Retrieves a list of people, projects, or companies based on specified filters and sorting criteria.

### Method
GET

### Endpoint
`/people` or `/projects` or `/companies`

### Parameters
#### Query Parameters
- **summaryonly** (boolean) - Optional - Returns a summary for each matching person, project, or company, typically the first email or phone. For feed operations, set this on the initial request.
- **includeauditedchanges** (boolean) - Optional - Requests the API to return a `_results` field, an array of JSON objects. There is one array entry per person. Each array entry is an object with 2 fields: the `_person`, `_project`, or `company` field returns the matching person, and the `_changes` field provides access to audited changes that have occurred since the relation was last delivered by the feed API. When you stream by default all existing relations are delivered. During initial delivery `_changed_` will be empty.
- **sort** (string) - Optional - Sort order. Possible values: `lastchanged`, `bestrelationship`, `firstmet`, `lasttalked`, `wentquiet`, `assigned`, `duenext`, `duepast`, `first`, `last`, `nextstep`, `distance`, `value`, `created`, `start`, `end`, `name`.
- **sortdir** (string) - Optional - Sort direction. Possible values: `asc`, `dec`.
- **group** (string) - Optional - Group order. Possible values: `stage`, `subteam`.
- **scope** (string) - Optional - Scope of relation (person, project, and company). May be a local relation, a team relation, or team relation within a hierarchy. For feed operations, set this on the initial request. Possible values: `local`, `team`, `hierarchy:/X/Y/Z`, `hierarchy:X/Y/Z/*`.
- **team** (boolean) - Optional - Identifies whether the team relation or local relation is to be retrieved or deleted.
- **modifiedafter** (string) - Optional - Specifies the starting point in time for looking for changes. Only records that are modified after this time are returned. Enter the time in UTC milliseconds. The value `now` sets the current UTC milliseconds time, and prepares the feed API for streaming future changes. Without `modifiedafter`, the feed APIs first return all matching records, and then streams changes since the cursor was first created.
- **freeformquery** (string) - Optional - Supports the same natural language query expressions that can be entered directly using the Cloze UI, or as a selected suggestion from the Cloze UI. May be used in conjunction with the other structured query parameter forms.
- **stage** (string) - Optional - Stage of the person, project or company. The value `none` indicates no stage set, `any` indicates that a stage is set. For feed operations, set this on the initial request. Possible values: `lead`, `future`, `current`, `past`, `out`.
- **hidelostdone** (boolean) - Optional - For projects, hide lost/done projects.
- **segment** (string) - Optional - Segment of the person, project or company. The value `none` indicates no segment set, `any` indicates that a segment is set. For feed operations, set this on the initial request. This can either be an underlying immutable segment id (e.g. "custom2") or the current name of the segment (e.g. "Buyer & Seller").
- **step** (string) - Optional - Unique Id of Next Step. The value `none` indicates no next step, `any` indicates that a next step is set.
- **assigned** (string) - Optional - Filter by assigned user.
```

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

### Get Recipient Lists

Source: https://developer.cloze.com/swagger.json

Retrieves recipient lists, including tags, audiences, and subscriptions, which can be used for sending mail merges.

```APIDOC
## GET /v1/user/recipients

### Description
Get the tags, audiences, and subscriptions that can be lists of recipients for sending mail merges.

### Method
GET

### Endpoint
/v1/user/recipients

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success.
- **message** (string) - If an error occurs, this is the human readable description.
- **keywords** (array) - Array of up to 100 tags, sorted by most frequently used first.
  - **id** (string) - tag id (without the hash sign)
  - **name** (string) - Human readable name of this tag (includes the hash sign)
  - **query** (string) - search query used to find people with this tag
- **views** (array) - Array of audiences that can be sent to.
  - **id** (string) - audience id
  - **name** (string) - Human readable name of this audience
```

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

### ProjectRef Object

Source: https://developer.cloze.com/swagger.json

Defines the structure for referencing a project, including synchronization keys and account details.

```APIDOC
## ProjectRef Object

### Description
This object is used to reference a project within the system. It includes fields for synchronization keys, portable IDs, and account-specific information.

### Properties
- **syncKey** (string) - Description: Internal Cloze key used to keep this record in-sync with external systems. Note that the syncKey for the same person may change over time as records are merged. Alternately, by using AppLinks you can provide external keys for a record to keep it in-sync.
- **portableId** (string) - Description: A portable ID can be used to find the equivalent person across user accounts.
- **account** (string) - Format: email - Description: Team administrators can use this to create the project in a different team member's account. This should be the email address of the team member. The user must be an administrator and have permission to import team data to do this. Set to "team" to import into the team.
- **name** (string) - Description: name of the project or deal
```

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

### Get Person

Source: https://developer.cloze.com/swagger.json

Retrieves a single person's record using a unique identifier such as email address, syncKey, or portableId.

```APIDOC
## GET /v1/people/get

### Description
Get person based on a unique identifier (for example, email address, syncKey, or portableId)

### Method
GET

### Endpoint
/v1/people/get

### Parameters
#### Query Parameters
- **personuniqueid** (string) - Required - The unique identifier for the person.
- **team** (boolean) - Optional - Identifies whether the team relation or local relation is to be retrieved or deleted.
- **queryformat** (string) - Optional - Specifies the desired format for the query results.

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success.
- **person** (object) - The person's record, referencing '#/definitions/PersonRef'.
```

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

### Create Subscription

Source: https://developer.cloze.com/swagger.json

Allows users to create a new webhook subscription to receive real-time notifications for various events within Cloze. This includes specifying the event type, target URL, scope, and optional filters and client information.

```APIDOC
## POST /subscriptions

### Description
Creates a new webhook subscription to receive notifications for specified events.

### Method
POST

### Endpoint
/subscriptions

### Parameters
#### Request Body
- **subscription** (object) - Required - The subscription to create.
  - **event** (string) - Required - Name of the event being subscribed to. Must be one of: "person.change", "project.change", "company.change", "person.audit.change", "project.audit.change", "company.audit.change".
  - **target_url** (string) - Required - Callback URL to be called by the webhook.
  - **scope** (string) - Required - Scope of subscription. Can be "local", "team", or "hierarchy:/X/Y/Z" or "hierarchy:/X/Y/Z/*".
  - **filters** (array) - Optional - Filters applied before delivering notifications. Each filter is an object that may contain "person", "project", or "company" keys with JSON fragments for matching, and optionally a "changes" key for filtering against change information. A "*" in a fragment acts as a wildcard.
  - **client_type** (string) - Optional - Client or implementation information (e.g., "human" for UI-like values).
  - **client_reference** (string) - Optional - Client-provided name for identifying and referencing subscriptions. Used for unsubscribing. Multiple subscriptions with the same event name and client reference will replace existing ones.

### Request Example
{
  "subscription": {
    "event": "person.change",
    "target_url": "https://example.com/webhook",
    "scope": "local",
    "filters": [
      {
        "person": {
          "name": "John Doe"
        }
      }
    ],
    "client_type": "my-app",
    "client_reference": "user-123"
  }
}

### Response
#### Success Response (200)
- **uniqueid** (string) - The unique identifier allocated by Cloze for the subscription.
- **event** (string) - The name of the event subscribed to.
- **target_url** (string) - The callback URL.
- **scope** (string) - The scope of the subscription.
- **filters** (array) - The filters applied to the subscription.
- **client_type** (string) - The client type.
- **client_reference** (string) - The client reference.

#### Response Example
{
  "uniqueid": "sub_abc123",
  "event": "person.change",
  "target_url": "https://example.com/webhook",
  "scope": "local",
  "filters": [
    {
      "person": {
        "name": "John Doe"
      }
    }
  ],
  "client_type": "my-app",
  "client_reference": "user-123"
}
```

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

### List Projects

Source: https://developer.cloze.com/swagger.json

Retrieves a list of projects with support for pagination, sorting, filtering, and searching. It allows for various query parameters to refine the results.

```APIDOC
## GET /v1/projects

### Description
Retrieves a list of projects with various filtering and sorting options.

### Method
GET

### Endpoint
/v1/projects

### Parameters
#### Query Parameters
- **pagesize** (integer) - Optional - Number of results to return per page.
- **pagenumber** (integer) - Optional - The page number to retrieve.
- **countonly** (boolean) - Optional - If true, only returns the total count of projects.
- **sort** (string) - Optional - Field to sort by.
- **sortdir** (string) - Optional - Direction of sort (asc or desc).
- **group** (string) - Optional - Field to group results by.
- **scope** (string) - Optional - Scope of the query.
- **freeformquery** (string) - Optional - Freeform search query.
- **hidelostdone** (boolean) - Optional - If true, hides lost or done projects.
- **stage** (string) - Optional - Filter by project stage.
- **segment** (string) - Optional - Filter by project segment.
- **step** (string) - Optional - Filter by project step.
- **assignee** (string) - Optional - Filter by assignee.
- **assigned** (boolean) - Optional - Filter by assigned status.
- **collaborator** (string) - Optional - Filter by collaborator.
- **queryformat** (string) - Optional - Format of the query.

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success.
- **pagenumber** (number) - Page number of returned data.
- **pagesize** (number) - Page size.
- **projects** (array) - Array of project records.

### Response Example
```json
{
  "Sample 1 Response to a countonly query": {
    "errorcode": 0,
    "availablecount": 6577
  },
  "Sample 2 Response to a regular query": {
    "errorcode": 0,
    "availablecount": 1,
    "pagenumber": 1,
    "pagesize": 20,
    "projects": [
      {
        "name": "School Placement",
        "node": "/US/West/CA",
        "direct": "JDTiwJTnmBPHANAgHELBAA",
        "segment": "project",
        "stage": "current"
      },
      "etc etc"
    ]
  }
}
```
```

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

### Get User Profile

Source: https://developer.cloze.com/swagger.json

Retrieves the profile information for the authorized user. This can be used to personalize the application or verify the connected user account.

```APIDOC
## GET /v1/user/profile

### Description
This API returns information about the user account that has been authorized. You can use this to personalize your app to the user, or to verify the correct user account was connected.

### Method
GET

### Endpoint
/v1/user/profile

### Parameters

### Request Body

### Request Example

### Response
#### Success Response (200)
- **errorcode** (number) - Error code. 0 means success
- **message** (string) - If an error occurs, this is the human readable description
- **profile** (object) - User profile details
  - **email** (string) - User's account email address
  - **phone** (string) - Best phone number for the user
  - **address** (object) - Work address for the user
  - **name** (string) - Full name of user
  - **first** (string) - First name of user
  - **last** (string) - Last name of user
  - **photo** (string) - User's profile photo URL
  - **key** (string) - Cloze's unique Id for this user
  - **country** (string) - User's country as an ISO 2 letter code
  - **aka** (array) - Other emails and unique IDs this user might be known by
    - **identifier** (string)
  - **scopes** (array) - Access scopes granted by the access token or api key
    - **scope** (string)
  - **rights** (array) - Rights granted to this user if they are a team member

#### Response Example
{
  "errorcode": 0,
  "message": "Success",
  "profile": {
    "email": "user@example.com",
    "phone": "+15551234567",
    "address": {
      "street": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "90210",
      "country": "US"
    },
    "name": "John Doe",
    "first": "John",
    "last": "Doe",
    "photo": "https://example.com/photo.jpg",
    "key": "user-cloze-id-12345",
    "country": "US",
    "aka": [
      "other@example.com",
      "alias-id-67890"
    ],
    "scopes": [
      "read",
      "write"
    ],
    "rights": [
      "admin"
    ]
  }
}
```