---
title: "PracticPro API | Connect Your Software and Apps"
description: "PracticPro's API for your own software and other apps: authenticate with an app key, send leads into a Data Source, create and find contacts, read projects and invoices, add notes, and subscribe to events with REST hooks."
url: https://practicpro.com/apps-api
---

# PracticPro API

Connect your own software or any app: send leads in, keep contacts up to date, and hear when something happens in PracticPro.

Last updated November 8, 2026

Every request runs as one person in one PracticPro company: the person who made the app key. It can see and change what that person can on their own screens, and nothing else.

**Availability:** the API is open to a limited set of companies for now. For any other company, every call answers `403` (`#apa00`). To join, write to [support@practicpro.com](mailto:support@practicpro.com).

Any app or script with an app key can use this API. Zapier is one way to connect, with no code. A machine-readable description of the API is at [OpenAPI 3.1](https://practicpro.com/static/openapi/practicpro-apps-api.json).

## Base URL and versions

Base URL

```
https://portal.practicpro.com/api/apps/v1
```

Requests and answers are JSON. Send `Content-Type: application/json` with every POST.

The version is in the path (`/v1`). Within v1, PracticPro only adds: new endpoints, new events, and new fields in answers. Nothing is renamed or removed, so read the fields you need and ignore the rest. A change that would break a working integration comes as `/v2`, announced ahead, with `/v1` kept running alongside it.

## Authentication

In PracticPro, open **Settings > Data Sources > API & Apps** and click **New app key**. The key starts with `ppk_` and is shown once; PracticPro keeps only a fingerprint of it. You choose what it can do (**Read and write**, or **Read only**: it can read and hold triggers but change nothing) and when it ends (never, or after 30 days, 90 days or a year). Making a key needs the **Connect apps and API** permission and a fresh login code, and one person can have up to 10 keys. The person and the company's owner are told by email. Send the key as a bearer token on every request:

Header

```
Authorization: Bearer ppk_YOUR_APP_KEY
```

A key works only on this API, never on PracticPro's pages, and only in the company it was made in. It stops working at once when it is removed or reaches its end date, when its person is deactivated or loses the Connect apps and API permission, when an administrator ends all of the person's sessions, or when the company's account is not active.

### Changing a key

In the key's **...** menu, choose **Replace key**. The old secret stops at once and a new one is shown once. The key keeps its name, access, end date and triggers, so deliveries continue; update your app with the new key so its requests keep working. **Remove key** is different: the key's triggers end with it.

### If a key leaks

Treat a key like a password: keep it out of code, tickets and chat. If one is exposed, replace or remove it right away. Then check the records it could reach; PracticPro's request log records each call with the key that made it.

## Errors

The HTTP status says what happened, and the body is always `{"error": "words to show the person #code"}`. The words are written for the person using your app; the code at the end names the exact check.

| Status | Meaning | Examples |
|---|---|---|
| `400` | Something in the request is wrong | Not a JSON object (`#apa06`), no `fields` object (`#apa25`), a bad `lead_id` (`#apa09`), a `page` from 1 to 400 (`#apa32`), a bad `before` or `updated_since` (`#apa39`, `#apa40`, `#apa41`), an `Idempotency-Key` over 200 characters (`#apa35`), a hook address that is not a public `https://` address (`#aph01`, `#aph05`) |
| `401` | No key, or a key that no longer works | `#apa01` |
| `403` | The key's person may not do this | A missing permission, named as PracticPro's screens name it (`#apa02`); Connect apps and API taken away (`#apa04`); the company's account is not active (`#apa24`); this key is read only (`#apa33`); the API not open for the company yet (`#apa00`) |
| `404` | Not found, or not one this person can see | `#apa03`, `#apa18`, `#apa22`, an address the API does not have (`#apa28`) |
| `405` | The address exists, the method does not | `#apa28` |
| `409` | Not now | The Data Source is paused and the lead has no `lead_id` (`#apa07`); the same lead is being recorded right now, try again in a moment (`#apa10`); this person is already a contact the key's person cannot see, and nothing was changed (`#apa34`); a request with this `Idempotency-Key` is still running (`#apa38`) |
| `413` | The request is too large | Over 1 MB (`#apa29`) |
| `422` | PracticPro refused the record | A required answer is missing (`#apa11`), the contact could not be saved (`#apa15`), an `Idempotency-Key` used on a different request (`#apa37`) |
| `429` | Too much at once | Wait the seconds in the `Retry-After` header, then try again |
| `500` | PracticPro could not answer | Try again in a moment (`#apa12`, `#apa14`, `#apa31`) |
| `503` | Could not promise "once" | The request had an `Idempotency-Key` and was not run. Try again (`#apa36`) |

Example: 403

```
{
  "error": "Sending leads into a Data Source that adds contacts needs \"Add contacts\" in PracticPro #apa02"
}
```

## Rate limits and sizes

PracticPro limits how much work one key's requests may cost, not how many there are: about 60 seconds of server time in any one minute and 300 seconds in any ten minutes, separate from that person's own use of PracticPro. Ordinary calls take a few hundredths of a second, so the limit is reached only by a runaway loop. Over it, the answer is `429` with a `Retry-After` header.

- A request: up to 1 MB.
- A lead: at most 100 fields. A field name is kept to 200 characters and a value to 5,000.
- A contact: each field is kept to 255 characters, `notes` to 5,000.
- A note: kept to 5,000 characters.
- Text past these lengths is cut, not refused. HTML tags in contact fields and notes are removed.
- Trigger subscriptions: up to 100 per key.

## Sending a request twice

To retry a `POST` safely when you did not get an answer, send an `Idempotency-Key` header of your choice, up to 200 characters. Every endpoint that changes records takes it. For 24 hours, the same key on the same request is answered with the first success and the header `Idempotent-Replayed: true`, and the work is not done again. A refused request does not use its key up. `POST /leads` also has its own `lead_id`, which never expires.

## Ids and dates

Every id is a typed public id: a short prefix, an underscore, and 11 letters and digits. The prefix says what the record is, and an id of one kind is never accepted as another.

| Prefix | Record | Example |
|---|---|---|
| `ds_` | Data Source | `ds_DMNRFLY2p27` |
| `ld_` | Lead (a Data Source submission) | `ld_3U7x4fuDmSv` |
| `ct_` | Contact | `ct_Hgf1eyWK0hE` |
| `pj_` | Project | `pj_CqmCquIGIR6` |
| `ap_` | Appointment | `ap_JPlvXXiMhit` |
| `in_` | Invoice | `in_DI49o4dU83e` |
| `dc_` | Document | `dc_ELNlIGFUIqw` |
| `tg_` | Trigger subscription | `tg_FKnfMdaKaiB` |
| `ev_` | Event (in trigger deliveries) | `ev_be85b7eb092abfbbe84b9015` |

Times are ISO 8601 in UTC with a `Z`, like `2026-11-03T17:20:00Z`. A value that is a day and not a moment (an invoice's due date, an all-day appointment) is the day alone, like `2026-11-10`. Phone numbers come back as PracticPro stores them, like `+18185550147`. A `zip` is text, like `"02134"`. Amounts are numbers in the company's currency, like `18500.0`. Field names are snake_case.

## Who the key belongs to

`GET /me` answers the company and the person the key acts as. Use it to test a key. Needs only the key.

Request

```
curl https://portal.practicpro.com/api/apps/v1/me \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY"
```

Answer: 200

```
{
  "company_name": "Rivera Remodeling",
  "key_name": "Zapier",
  "person": "Dana Ruiz"
}
```

## Data Sources

`GET /data_sources` lists the active Data Sources a lead can go into, by name. `platform` names the platform whose Data Source it is (`yelp`), else `null`; a lead sent into it with no platform, or with `zapier`, is filed under that platform. `help` is what to show above its inputs and under Lead ID (`step`, `lead_id`), else `null`. Needs **See data sources**.

Request

```
curl https://portal.practicpro.com/api/apps/v1/data_sources \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY"
```

Answer: 200

```
[
  {
    "id": "ds_DMNRFLY2p27",
    "name": "Website leads",
    "platform": null,
    "help": null
  },
  {
    "id": "ds_K3wPq81xLm0",
    "name": "Yelp",
    "platform": "yelp",
    "help": {
      "step": "Fill each box with **Yelp's value of the same name** ...",
      "lead_id": "Pick \"Yelp Lead ID\" from Yelp ..."
    }
  }
]
```

`GET /data_sources/{id}/fields` lists the answers the Data Source takes: `key` is the name to send in a lead's `fields`, `label` is what to show a person, `help` the hint under it ("" when there is none). Needs **See data sources**.

Request

```
curl https://portal.practicpro.com/api/apps/v1/data_sources/ds_DMNRFLY2p27/fields \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY"
```

Answer: 200

```
[
  {
    "key": "first_name",
    "label": "First name",
    "required": true,
    "help": ""
  },
  {
    "key": "email",
    "label": "Email",
    "required": false,
    "help": ""
  },
  {
    "key": "phone",
    "label": "Phone",
    "required": false,
    "help": ""
  }
]
```

## Create a lead

`POST /leads` sends a lead into a Data Source, exactly as its own webhook would. The Data Source decides what is made: the submission alone, a contact (made, or matched to the same person already in PracticPro), or a contact and an appointment. Needs **See data sources**, and **Add contacts** when the Data Source adds contacts.

Request

```
curl -X POST https://portal.practicpro.com/api/apps/v1/leads \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data_source_id": "ds_DMNRFLY2p27",
    "platform": "yelp",
    "lead_id": "abc123",
    "fields": {"first_name": "Ada", "email": "ada@example.com"}
  }'
```

Answer: 200

```
{
  "answers": {
    "email": "ada@example.com",
    "first_name": "Ada"
  },
  "contact": {
    "address": "",
    "address_two": "",
    "city": "",
    "company_name": "",
    "country": "",
    "created_at": "2026-11-03T17:20:00Z",
    "custom_fields": {},
    "email": "ada@example.com",
    "first_name": "Ada",
    "full_name": "Ada",
    "id": "ct_Hgf1eyWK0hE",
    "last_name": "",
    "lead_source": "",
    "name": "Ada",
    "notes": "",
    "phone": "",
    "phone_two": "",
    "state": "",
    "updated_at": "2026-11-03T17:20:00Z",
    "url": "https://portal.practicpro.com/apps/open/ct_Hgf1eyWK0hE",
    "zip": ""
  },
  "data_source": "Website leads",
  "data_source_id": "ds_DMNRFLY2p27",
  "duplicate": false,
  "held": false,
  "id": "ld_3U7x4fuDmSv",
  "received_at": "2026-11-03T17:20:00Z",
  "url": "https://portal.practicpro.com/apps/open/ld_3U7x4fuDmSv"
}
```

- `data_source_id` (required) and `fields` (required): an object of answers, by the keys from `/fields`. `true`, `false` and numbers are kept as written; objects and lists inside are left out.
- `platform` (optional, default `api`): a short name for where the lead comes from, lowercase letters, digits or `_`, up to 32.
- `lead_id` (optional, strongly advised): the lead's own id in that app, letters, digits, `-` or `_`, up to 50. With it, the same `platform` + `lead_id` is taken once: sending it again answers the first result with `"duplicate": true`. A lead PracticPro refused (`422`, a required answer missing) does not use its `lead_id` up, so the corrected lead can be sent again with the same one.
- A paused Data Source: a lead with a `lead_id` is **kept**, answered `202` with `"held": true`, and recorded when a person turns the Data Source back on. Without a `lead_id` it is refused with `409`.
- `contact` is `null` when the Data Source records submissions only, or while the lead is held.

## Add a message to a lead

`POST /leads/messages` adds a message about a lead an app sent before (Yelp's New Consumer Message or New Business Message) to the Messages of that lead's contact. Send the same `platform` and `lead_id` the lead was created with, the `text`, `from` (`customer` or `business`), and optionally the message's own `message_id` (the same message is added once) and the customer's `name`. A message that arrives before its lead waits for it. A `business` message that is a reply written in PracticPro coming back is not added twice. Needs **Edit contacts**. Answers `{"ok": true, "outcome": "written" | "waiting" | "duplicate", "words": "..."}`.

## Update a lead

`POST /leads/update` adds what an app sends later about a lead (for example the phone number Yelp shares after the first message) to the contact that lead made. Send the same `platform` and `lead_id` the lead was created with, any contact fields (see Create or update a contact), and an optional `note` for the contact's timeline. Needs **Edit contacts**.

It fills **empty** fields only and never overwrites a value. An email must be an email and a phone a phone number, and neither may be one another contact already has (that would make two people one). `filled` lists the fields it filled and `skipped` the ones it left, with why, by the names you sent.

Request

```
curl -X POST https://portal.practicpro.com/api/apps/v1/leads/update \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "yelp",
    "lead_id": "abc123",
    "phone": "(818) 555-0147",
    "email": "not an email",
    "note": "Asked for a call back after 5 PM"
  }'
```

Answer: 200

```
{
  "address": "",
  "address_two": "",
  "city": "",
  "company_name": "",
  "country": "",
  "created_at": "2026-11-03T17:20:00Z",
  "custom_fields": {},
  "email": "",
  "first_name": "Ada",
  "filled": [
    "phone"
  ],
  "full_name": "Ada",
  "id": "ct_Hgf1eyWK0hE",
  "last_name": "",
  "lead_source": "",
  "name": "Ada",
  "notes": "",
  "phone": "+18185550147",
  "phone_two": "",
  "skipped": [
    {
      "field": "email",
      "reason": "not an email address"
    }
  ],
  "state": "",
  "updated_at": "2026-11-03T17:20:00Z",
  "url": "https://portal.practicpro.com/apps/open/ct_Hgf1eyWK0hE",
  "zip": ""
}
```

A `404` (`#apa18`) means no lead with that `platform` and `lead_id` has made a contact yet.

## Create or update a contact

`POST /contacts` adds a contact, or fills the empty fields of the same person when they are already in PracticPro (the same email, the same phone, or the same name at the same street address). Nothing a person typed is overwritten. A contact needs a phone number or an email. Needs **Add contacts**.

- An email shared with a very different name (under 75% alike) is treated as a different person, so a new contact is made. A shared office or vendor email does not merge two people.
- Filling an existing contact also needs **Edit contacts**. Without it, the contact is answered as it is, with `"changed": false`.
- When the match is a contact the key's person cannot see, nothing is written and the answer is `409` (`#apa34`).
- `created` says whether the contact is new. `skipped` lists fields left out, with why.

Fields: `first_name`, `last_name`, `email`, `phone`, `phone_two`, `company_name`, `address`, `address_two`, `city`, `state`, `zip`, `country`, `lead_source`, `notes`.

Request

```
curl -X POST https://portal.practicpro.com/api/apps/v1/contacts \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ada",
    "last_name": "Lovelace",
    "email": "ada@example.com",
    "phone": "818-555-0147",
    "address": "120 Main St",
    "city": "Springfield",
    "state": "CA",
    "zip": "90210",
    "lead_source": "Website"
  }'
```

Answer: 200, the contact

```
{
  "address": "120 Main St",
  "address_two": "",
  "changed": true,
  "city": "Springfield",
  "company_name": "",
  "country": "",
  "created": true,
  "created_at": "2026-11-03T17:20:00Z",
  "custom_fields": {},
  "email": "ada@example.com",
  "first_name": "Ada",
  "full_name": "Ada Lovelace",
  "id": "ct_Hgf1eyWK0hE",
  "last_name": "Lovelace",
  "lead_source": "Website",
  "name": "Ada Lovelace",
  "notes": "",
  "phone": "+18185550147",
  "phone_two": "",
  "skipped": [],
  "state": "CA",
  "updated_at": "2026-11-03T17:20:00Z",
  "url": "https://portal.practicpro.com/apps/open/ct_Hgf1eyWK0hE",
  "zip": "90210"
}
```

## Find a contact

`GET /contacts/find` finds a contact by `email`, `phone`, or both (the email is tried first; a phone can be written any way). It searches only the contacts the key's person can see and answers a list: one contact, or `[]` when there is none. Needs **View contact records**.

Request

```
curl -G https://portal.practicpro.com/api/apps/v1/contacts/find \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY" \
  --data-urlencode "phone=(818) 555-0147"
```

Answer: 200

```
[
  {
    "address": "120 Main St",
    "address_two": "",
    "city": "Springfield",
    "company_name": "",
    "country": "",
    "created_at": "2026-11-03T17:20:00Z",
    "custom_fields": {},
    "email": "ada@example.com",
    "first_name": "Ada",
    "full_name": "Ada Lovelace",
    "id": "ct_Hgf1eyWK0hE",
    "last_name": "Lovelace",
    "lead_source": "Website",
    "name": "Ada Lovelace",
    "notes": "",
    "phone": "+18185550147",
    "phone_two": "",
    "state": "CA",
    "updated_at": "2026-11-03T17:20:00Z",
    "url": "https://portal.practicpro.com/apps/open/ct_Hgf1eyWK0hE",
    "zip": "90210"
  }
]
```

## List contacts

`GET /contacts` lists the contacts the key's person can see, 25 a page, newest first. With `search`, it finds them the way PracticPro's own contact search does: every word in the name, company, email, phone, address or notes, name matches first. `page` runs from 1 to 400; a page with fewer than 25 is the last. Needs **View contact records**. See Paging and changes to read further.

Request

```
curl -G https://portal.practicpro.com/api/apps/v1/contacts \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY" \
  --data-urlencode "search=ada lovelace" \
  --data-urlencode "page=1"
```

Answer: 200

```
[
  {
    "address": "120 Main St",
    "address_two": "",
    "city": "Springfield",
    "company_name": "",
    "country": "",
    "created_at": "2026-11-03T17:20:00Z",
    "custom_fields": {},
    "email": "ada@example.com",
    "first_name": "Ada",
    "full_name": "Ada Lovelace",
    "id": "ct_Hgf1eyWK0hE",
    "last_name": "Lovelace",
    "lead_source": "Website",
    "name": "Ada Lovelace",
    "notes": "",
    "phone": "+18185550147",
    "phone_two": "",
    "state": "CA",
    "updated_at": "2026-11-03T17:20:00Z",
    "url": "https://portal.practicpro.com/apps/open/ct_Hgf1eyWK0hE",
    "zip": "90210"
  }
]
```

## List projects

`GET /projects` lists the projects the key's person can see, 25 a page, newest first. With `search`, every word must be in the project's address, client, type, description or notes; a project's own number finds that project first. `page` runs from 1 to 400. Needs **View projects** (PracticPro shows the company's own word for projects). `sales_total` is `null` unless the person can see project finances.

Request

```
curl -G https://portal.practicpro.com/api/apps/v1/projects \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY" \
  --data-urlencode "search=main st" \
  --data-urlencode "page=1"
```

Answer: 200

```
[
  {
    "address": "120 Main St, Springfield CA 90210",
    "closed_at": null,
    "contact": {
      "address": "120 Main St",
      "address_two": "",
      "city": "Springfield",
      "company_name": "",
      "country": "",
      "created_at": "2026-11-03T17:20:00Z",
      "custom_fields": {},
      "email": "ada@example.com",
      "first_name": "Ada",
      "full_name": "Ada Lovelace",
      "id": "ct_Hgf1eyWK0hE",
      "last_name": "Lovelace",
      "lead_source": "Website",
      "name": "Ada Lovelace",
      "notes": "",
      "phone": "+18185550147",
      "phone_two": "",
      "state": "CA",
      "updated_at": "2026-11-03T17:20:00Z",
      "url": "https://portal.practicpro.com/apps/open/ct_Hgf1eyWK0hE",
      "zip": "90210"
    },
    "created_at": "2026-11-03T17:25:00Z",
    "custom_fields": {
      "Permit number": "B-2211"
    },
    "description": "Kitchen remodel",
    "id": "pj_CqmCquIGIR6",
    "name": "120 Main St, Springfield - Ada Lovelace",
    "project_type": "Remodel",
    "sales_total": 18500.0,
    "status": "In Progress",
    "updated_at": "2026-11-03T17:25:00Z",
    "url": "https://portal.practicpro.com/apps/open/pj_CqmCquIGIR6"
  }
]
```

## List invoices

`GET /invoices` lists the client invoices the key's person can see, 25 a page, newest first. Needs **See client invoices**.

Request

```
curl https://portal.practicpro.com/api/apps/v1/invoices \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY"
```

## Read one record

`GET /contacts/{id}`, `GET /projects/{id}` and `GET /invoices/{id}` answer one record in the shape shown under Records sent, or `404` when it is not one this person can see. They need the same permission as the list.

## Paging and changes

The lists of contacts, projects and invoices take two more parameters. They do not go with `search`.

- `before`: the `id` of the last row you read. The answer goes on from there, so a list can be read past page 400. The first page has no `before`.
- `updated_since`: an ISO 8601 time. Only records PracticPro recorded a change on at or after it.

Request

```
curl -G https://portal.practicpro.com/api/apps/v1/contacts \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY" \
  --data-urlencode "before=ct_Hgf1eyWK0hE" \
  --data-urlencode "updated_since=2026-11-01T00:00:00Z"
```

## Add a note

`POST /notes` adds a note to a contact's or a project's timeline, as the key's person. Send `text` and either `contact_id` or `project_id`; with both, the note goes on the project. Needs **View contact records** for a contact, and **View projects** for a project (PracticPro shows the company's own word for projects).

Request

```
curl -X POST https://portal.practicpro.com/api/apps/v1/notes \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "ct_Hgf1eyWK0hE",
    "text": "Called back, booked a visit"
  }'
```

Answer: 201

```
{
  "contact_id": "ct_Hgf1eyWK0hE",
  "ok": true,
  "project_id": null,
  "text": "Called back, booked a visit"
}
```

## Triggers (REST hooks)

`POST /hooks` subscribes an address of yours to one event. It must be a public `https://` address on a host name, with no port and no user part. Subscribing needs the event's permission (see Events). The answer is `201` with the subscription; the same event to the same address again answers the same subscription with `200`, so a retried subscribe never sends events twice. Both answers carry the subscription's `secret`: keep it to verify deliveries.

Request

```
curl -X POST https://portal.practicpro.com/api/apps/v1/hooks \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "contact.created",
    "target_url": "https://example.com/practicpro/hook"
  }'
```

Answer: 201

```
{
  "event": "contact.created",
  "id": "tg_FKnfMdaKaiB",
  "secret": "whsec_kS3nV0pYt2mQ8xLd7Wc1rUe9oBz4hJa6fGi5"
}
```

`GET /hooks` lists this key's subscriptions, with `created_at`, `last_sent_at`, `last_status` and `failures`, never the secret.

`DELETE /hooks/{id}` unsubscribes.

Request

```
curl -X DELETE https://portal.practicpro.com/api/apps/v1/hooks/tg_FKnfMdaKaiB \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY"
```

Answer: 200

```
{
  "id": "tg_FKnfMdaKaiB",
  "removed": true
}
```

`GET /samples/{event}` answers the newest real record of that event the person can see, in the exact shape a delivery has, for setting up your side: a list of one, or `[]`. Needs the event's permission.

Request

```
curl https://portal.practicpro.com/api/apps/v1/samples/invoice.paid \
  -H "Authorization: Bearer ppk_YOUR_APP_KEY"
```

Answer: 200

```
[
  {
    "created_at": "2026-11-01T17:20:00Z",
    "description": "Deposit",
    "due": 0.0,
    "due_at": "2026-11-10",
    "event": "invoice.paid",
    "event_id": "ev_5d1c0e9a77b24f3e8a1b6c20",
    "id": "in_DI49o4dU83e",
    "occurred_at": "2026-11-03T17:25:41Z",
    "paid": 5000.0,
    "paid_at": "2026-11-03T17:20:00Z",
    "project_id": "pj_CqmCquIGIR6",
    "status": "Paid",
    "total": 5000.0,
    "updated_at": "2026-11-03T17:20:00Z",
    "url": "https://portal.practicpro.com/apps/open/in_DI49o4dU83e"
  }
]
```

### Deliveries

When an event happens, PracticPro POSTs its record to the subscription's address, with the headers `X-PracticPro-Event`, `X-PracticPro-Event-Id`, `X-PracticPro-Timestamp` and `X-PracticPro-Signature`. Every delivery carries `event`, `event_id` and `occurred_at` beside the record's own fields.

A delivery

```
POST https://example.com/practicpro/hook
Content-Type: application/json
X-PracticPro-Event: contact.created
X-PracticPro-Event-Id: ev_be85b7eb092abfbbe84b9015
X-PracticPro-Timestamp: 1793726400
X-PracticPro-Signature: v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

{
  "address": "120 Main St",
  "address_two": "",
  "city": "Springfield",
  "company_name": "",
  "country": "",
  "created_at": "2026-11-03T17:20:00Z",
  "custom_fields": {},
  "email": "ada@example.com",
  "event": "contact.created",
  "event_id": "ev_be85b7eb092abfbbe84b9015",
  "first_name": "Ada",
  "full_name": "Ada Lovelace",
  "id": "ct_Hgf1eyWK0hE",
  "last_name": "Lovelace",
  "lead_source": "Website",
  "name": "Ada Lovelace",
  "notes": "",
  "occurred_at": "2026-11-03T17:20:01Z",
  "phone": "+18185550147",
  "phone_two": "",
  "state": "CA",
  "updated_at": "2026-11-03T17:20:00Z",
  "url": "https://portal.practicpro.com/apps/open/ct_Hgf1eyWK0hE",
  "zip": "90210"
}
```

- Each event is sent once per subscription. When a delivery fails, it is sent again after 1 minute, 5 minutes, 30 minutes and 2 hours, with the same `event_id`, so a repeat can be recognised. Every new event (the same project moving to another status again, for example) has its own `event_id`.
- Only a `2xx` answer means delivered; a redirect counts as a failure. `410` removes the subscription: answer it when you no longer want the events. After 20 events in a row that could not be delivered, the subscription is removed.
- A delivery waits up to 15 seconds for the answer and follows no redirects.
- The record is read as the key's person sees it at the moment it is sent: a record they cannot see is not sent. Deliveries stop while the person lacks Connect apps and API or the event's permission, is held to the company's login locations, and while the company's account is not active.

### Verifying a delivery

Every delivery is signed with the subscription's `secret`. Compute HMAC-SHA256 of the timestamp, a dot, and the raw request body, and compare it with the value after `v1=`. Reject a timestamp more than a few minutes old.

Python

```
import hashlib, hmac, time

def is_from_practicpro(secret, timestamp, signature, raw_body):
    if abs(time.time() - int(timestamp)) > 300:
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = "v1=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)
```

## Events

| Event | When | Record sent | Needs |
|---|---|---|---|
| `contact.created` | A contact is added | Contact | View contact records |
| `lead.received` | A Data Source receives a lead | Lead | See data sources |
| `project.status_changed` | A project moves to another status (every move) | Project | View projects |
| `appointment.booked` | An event is added to the calendar (never a task or a step of a project plan) | Appointment | See own events and tasks |
| `document.signed` | Every recipient has signed a document. `finalized_at` stays empty until someone finalizes it | Document | See project files |
| `document.finalized` | A document is finalized | Document | See project files |
| `invoice.paid` | A client invoice is paid in full | Invoice | See client invoices |
| `invoice.sent` | A client invoice reaches the client by email or text | Invoice | See client invoices |
| `project.created` | A project is added | Project | View projects |
| `task.completed` | A task is marked done | Appointment | See own events and tasks |
| `lead.reply` | Someone replies to an app's lead (Yelp) from its contact's Messages: send it on with the platform's own action (Yelp Leads > Create Message) | Reply | View contact records |

## Records sent

The exact fields of each record, in deliveries, samples and answers alike. `contact` inside another record is the full contact, or `null`.

| Record | Fields |
|---|---|
| Contact | `id`, `name` (the person, else their company, else their email), `first_name`, `last_name`, `full_name`, `company_name`, `email`, `phone`, `phone_two`, `address`, `address_two`, `city`, `state`, `zip`, `country`, `lead_source`, `notes`, `custom_fields` (by field name, the ones this person can see), `created_at`, `updated_at`, `url` |
| Lead | `id`, `data_source_id`, `data_source`, `received_at`, `answers` (as sent), `contact`, `url` |
| Project | `id`, `name` (how PracticPro names a project: its address, then its client), `status`, `project_type`, `description`, `address`, `created_at`, `updated_at`, `closed_at`, `sales_total` (`null` unless the person can see project finances), `custom_fields`, `contact`, `url` |
| Appointment | `id`, `title`, `status`, `description`, `starts_at`, `ends_at`, `all_day` (then `starts_at` and `ends_at` are days), `project_id`, `contact`, `url` |
| Document | `id`, `name`, `status`, `total`, `project_id`, `signed_at`, `finalized_at`, `url` |
| Invoice | `id`, `status`, `description`, `total`, `paid`, `due`, `due_at` (a day), `paid_at`, `created_at`, `updated_at`, `project_id`, `url` |
| Every delivery and sample adds | `event`, `event_id`, `occurred_at` |

`url` opens the record in PracticPro, for a person who can see it there.

## Using Zapier

The **PracticPro app on Zapier** is built on this API and needs no code. Make an app key, add PracticPro in Zapier and paste the key. Its triggers and actions are the ones described here.

## Changes

- **November 8, 2026 (later):** open to any app. Triggers can go to any public `https://` address, and every delivery is signed. A lead's `platform` defaults to `api`.
- **November 8, 2026:** read-only keys, key end dates and Replace key; `Idempotency-Key`; `GET /hooks`, `/contacts/{id}`, `/projects/{id}` and `/invoices`; `before` and `updated_since`; `custom_fields`, `updated_at`, `signed_at`; four new events; `created` and `changed` on `POST /contacts`. `zip` is always text, `url` carries the public id, `is_task` is gone, and `sales_total` follows the person's project finance access.
- **November 3, 2026:** first version.

**Questions?** Write to [support@practicpro.com](mailto:support@practicpro.com).

Last updated November 8, 2026
