API Access + Webhooks

Programmatic access to your Person Trail data via REST API and real-time webhook notifications.

Overview

The Person Trail REST API lets you read and create data programmatically. Webhooks deliver real-time notifications to your URL when events occur. Both features are available exclusively on the Trailblazer plan.

Authentication

All API requests require a Bearer token. Create API keys in Settings > API Access + Webhooks.

curl -H "Authorization: Bearer pt_live_your_key_here" \
  https://www.persontrail.com/api/v1/jobs

API keys are shown once at creation. Store them securely. Do not expose keys in client-side code or public repositories.

Rate Limits

100 requests per minute per API key
Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Exceeding the limit returns HTTP 429

Endpoints

Jobs

Method	Path	Description
GET	`/api/v1/jobs`	List jobs (paginated)
GET	`/api/v1/jobs/:id`	Get a single job with phases and assignments
POST	`/api/v1/jobs`	Create a new job

Query parameters for list: ?status=completed&priority=high&page=1&per_page=50

Crew Members

Method	Path	Description
GET	`/api/v1/contractors`	List crew members (paginated)
GET	`/api/v1/contractors/:id`	Get a single crew member

Clients

Method	Path	Description
GET	`/api/v1/clients`	List clients (paginated)
GET	`/api/v1/clients/:id`	Get a single client

Invoices

Method	Path	Description
GET	`/api/v1/invoices`	List invoices with line items (paginated)
GET	`/api/v1/invoices/:id`	Get a single invoice with line items

Query parameters for list: ?status=paid&page=1&per_page=50

Response Format

List response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 123
  }
}

Single resource

{
  "data": { ... }
}

Error response

{
  "error": {
    "code": "not_found",
    "message": "Job not found"
  }
}

Pagination

All list endpoints support offset-based pagination:

page (default: 1)
per_page (default: 50, max: 100)

Webhooks

Webhooks deliver HTTP POST notifications to your URL when events happen in your account. Configure endpoints in Settings > API Access + Webhooks.

Available Events

Event	Description
`job.created`	A new job was created
`job.updated`	A job was updated
`job.completed`	A job was marked as complete
`job.started`	A job was started
`job.delayed`	A job was delayed
`invoice.created`	A new invoice was created
`invoice.paid`	An invoice was marked as paid
`invoice.sent`	An invoice was sent
`estimate.created`	A new estimate was created
`estimate.approved`	An estimate was approved
`crew.rated`	A crew member was rated
`message.sent`	A job message was sent

Subscribe to specific events or use * for all events.

Webhook Headers

Each delivery includes:

X-PersonTrail-Signature - HMAC-SHA256 signature for verification
X-PersonTrail-Event - Event type (e.g., job.completed)
X-PersonTrail-Delivery - Unique delivery ID
X-PersonTrail-Timestamp - Unix timestamp

Verifying Signatures

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const parts = Object.fromEntries(
    signature.split(',').map(p => p.split('='))
  );
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${payload}`)
    .digest('hex');
  return parts.v1 === expected;
}

Retries

Failed deliveries (non-2xx responses or timeouts) are retried up to 3 times:

First retry: 1 minute after failure
Second retry: 5 minutes after first retry
Third retry: 30 minutes after second retry

Testing

Use the "Test" button in Settings to send a test payload to your endpoint and verify your setup.

Limits

Maximum 5 API keys per organization
Maximum 5 webhook endpoints per organization
Webhook URLs must use HTTPS
Webhook payload timeout: 10 seconds