# Public API reference

Every endpoint of the public API, generated from its live OpenAPI document.

Generated from the live OpenAPI document at `https://api.pylosystem.com/api/v1/openapi.json`. Read [the API overview](/docs/api) first for tokens and limits.

Read-only access to one PYLO workspace's sales figures, for dashboards and tools that read PYLO live. Create a token in PYLO under Settings, API tokens, and send it as `Authorization: Bearer <token>`. A token reads exactly one workspace, the one it was created in, and can never write: PYLO stays the system of record.

## Base URL

- `https://api.pylosystem.com`

## Authentication

- **bearerToken**: HTTP bearer. A PYLO API token, pylo_ followed by 64 hex characters.

## Endpoints

### GET `/api/v1/whoami`

**Check a token**

The workspace and token this request is authenticated as. The first call any integration should make. Read only.

| Response | Meaning |
|---|---|
| 200 | The answer. Returns object. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/calls`

**Call figures**

Calls booked, taken, closed and the rates between them, for the period, each with both sides of every rate. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string | no | First day, YYYY-MM-DD. Defaults to 29 days before `to`. |
| `to` | query | string | no | Last day, YYYY-MM-DD. Defaults to today. |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/outcomes`

**Call outcomes**

Every call outcome in the period, counted. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string | no | First day, YYYY-MM-DD. Defaults to 29 days before `to`. |
| `to` | query | string | no | Last day, YYYY-MM-DD. Defaults to today. |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/payments`

**Cash and revenue**

Cash collected and revenue booked in the period, on the workspace's currency. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string | no | First day, YYYY-MM-DD. Defaults to 29 days before `to`. |
| `to` | query | string | no | Last day, YYYY-MM-DD. Defaults to today. |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/leads`

**Leads**

Leads created in the period, newest first, at most 500. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string | no | First day, YYYY-MM-DD. Defaults to 29 days before `to`. |
| `to` | query | string | no | Last day, YYYY-MM-DD. Defaults to today. |
| `limit` | query | integer | no | At most 500; a larger number is capped, not refused. |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/leads/{id}/journey`

**One lead's journey**

Everything PYLO holds about one lead, in order: how they arrived, their calls, outcomes and payments. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/speed-to-lead`

**Waiting leads**

Leads still waiting for a first contact, how long each has waited, and where to open them. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `withinMinutes` | query | integer | no |  |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/eod`

**End of day reports**

EOD submissions and compliance for the period. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string | no | First day, YYYY-MM-DD. Defaults to 29 days before `to`. |
| `to` | query | string | no | Last day, YYYY-MM-DD. Defaults to today. |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/attribution`

**Attribution**

Leads, closes and cash by UTM source, medium, campaign and content. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string | no | First day, YYYY-MM-DD. Defaults to 29 days before `to`. |
| `to` | query | string | no | Last day, YYYY-MM-DD. Defaults to today. |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/commission`

**Commission**

Commission owed per member for the period. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string | no | First day, YYYY-MM-DD. Defaults to 29 days before `to`. |
| `to` | query | string | no | Last day, YYYY-MM-DD. Defaults to today. |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/funnel`

**Funnel**

One funnel's stages for the period, each with its count and the rate from the stage before. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string | no | First day, YYYY-MM-DD. Defaults to 29 days before `to`. |
| `to` | query | string | no | Last day, YYYY-MM-DD. Defaults to today. |
| `funnel` | query | string | no | Which funnel. An unknown name answers 400 naming the ones that exist. |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/webinar`

**Webinar**

Registrations, attendance, stay to pitch and bookings, for one webinar event or all of them. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string | no | First day, YYYY-MM-DD. Defaults to 29 days before `to`. |
| `to` | query | string | no | Last day, YYYY-MM-DD. Defaults to today. |
| `eventId` | query | string | no | One webinar event. Omit for all of them. |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

### GET `/api/v1/audit-events`

**Audit log**

Every write recorded for this workspace in the period, with the actor, the target and the reason. Read only.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `from` | query | string | no | First day, YYYY-MM-DD. Defaults to 29 days before `to`. |
| `to` | query | string | no | Last day, YYYY-MM-DD. Defaults to today. |

| Response | Meaning |
|---|---|
| 200 | The answer. Returns Envelope. |
| 400 | A parameter PYLO cannot use, named. Returns Error. |
| 401 | No token, or one PYLO does not accept. Returns Error. |

## Schemas

### Envelope

Every answer. `notes` names anything PYLO could not answer, so a short list and a broken one never look the same.

| Field | Type | Required | Description |
|---|---|---|---|
| `workspace` | object | yes |  |
| `period` | object | no |  |
| `data` | object | yes | The answer. Figures inside it have the Field shape. |
| `notes` | array of object | yes |  |

### Field

One figure. `value` is null whenever PYLO could not honestly draw it, and `unavailable` then says why. A rate is a fraction, never a percentage, and carries both of its sides.

| Field | Type | Required | Description |
|---|---|---|---|
| `metric` | string | yes | The metric registry id. |
| `label` | string | yes |  |
| `unit` | string: count, money, rate | yes |  |
| `value` | number | yes |  |
| `currency` | string | no | Money only. ISO 4217. |
| `numerator` | object | no |  |
| `denominator` | object | no |  |
| `unavailable` | object | no |  |

### Error

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | object | no |  |