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.

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.

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.

StatusMeaningExamples
400Something in the request is wrongNot 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)
401No key, or a key that no longer works#apa01
403The key's person may not do thisA 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)
404Not found, or not one this person can see#apa03, #apa18, #apa22, an address the API does not have (#apa28)
405The address exists, the method does not#apa28
409Not nowThe 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)
413The request is too largeOver 1 MB (#apa29)
422PracticPro refused the recordA required answer is missing (#apa11), the contact could not be saved (#apa15), an Idempotency-Key used on a different request (#apa37)
429Too much at onceWait the seconds in the Retry-After header, then try again
500PracticPro could not answerTry again in a moment (#apa12, #apa14, #apa31)
503Could 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.

PrefixRecordExample
ds_Data Sourceds_DMNRFLY2p27
ld_Lead (a Data Source submission)ld_3U7x4fuDmSv
ct_Contactct_Hgf1eyWK0hE
pj_Projectpj_CqmCquIGIR6
ap_Appointmentap_JPlvXXiMhit
in_Invoicein_DI49o4dU83e
dc_Documentdc_ELNlIGFUIqw
tg_Trigger subscriptiontg_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

EventWhenRecord sentNeeds
contact.createdA contact is addedContactView contact records
lead.receivedA Data Source receives a leadLeadSee data sources
project.status_changedA project moves to another status (every move)ProjectView projects
appointment.bookedAn event is added to the calendar (never a task or a step of a project plan)AppointmentSee own events and tasks
document.signedEvery recipient has signed a document. finalized_at stays empty until someone finalizes itDocumentSee project files
document.finalizedA document is finalizedDocumentSee project files
invoice.paidA client invoice is paid in fullInvoiceSee client invoices
invoice.sentA client invoice reaches the client by email or textInvoiceSee client invoices
project.createdA project is addedProjectView projects
task.completedA task is marked doneAppointmentSee own events and tasks
lead.replySomeone 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)ReplyView 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.

RecordFields
Contactid, 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
Leadid, data_source_id, data_source, received_at, answers (as sent), contact, url
Projectid, 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
Appointmentid, title, status, description, starts_at, ends_at, all_day (then starts_at and ends_at are days), project_id, contact, url
Documentid, name, status, total, project_id, signed_at, finalized_at, url
Invoiceid, status, description, total, paid, due, due_at (a day), paid_at, created_at, updated_at, project_id, url
Every delivery and sample addsevent, 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.