AgenciesWP REST API Documentation

Overview

The AgenciesWP REST API lets you read and write your clients, projects, invoices, time logs and more from your own systems, or from Zapier, n8n and Make through their HTTP modules. It runs inside your own WordPress site, so your data never passes through a third-party service.

Messages and the activity log are not available through the API.

Base URL

Every request goes to the REST namespace on your own site:

https://your-site.com/wp-json/agencieswp/v1

Creating a key

In WordPress admin, go to Agencies WP → Settings → API. Give the key a label you will recognise later, such as “Zapier” or “Our CRM”, tick the permissions it needs, and save.

A key looks like this:

awp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys can be revoked at any time. A revoked key stops working immediately.

Authenticating

Send the key in a header. Either of these works:

Authorization: Bearer awp_your_key_here

X-AgenciesWP-Key: awp_your_key_here

Checking it works

curl -s https://your-site.com/wp-json/agencieswp/v1/ 
  -H "Authorization: Bearer awp_your_key_here"

{
  "name": "AgenciesWP API",
  "version": "1.2",
  "namespace": "agencieswp/v1",
  "key": "Zapier",
  "scopes": ["read:clients", "read:projects", "write:projects"],
  "notes": "This API never deletes. There are no delete routes.",
  "endpoints": { "...": "..." }
}

The index tells you which key you are using and exactly what it can reach, which makes it the quickest way to debug a permission error.

Permissions

A key holds whichever of these you grant it. Read permissions expose data. Write permissions create and update records, and never delete them.

Endpoints

Reading

Writing

Listing and pagination

Query parameters

Pagination headers

Every list response carries these headers. Page through until page reaches X-WP-TotalPages.

X-WP-Total: 143
X-WP-TotalPages: 6

Example

curl -s "https://your-site.com/wp-json/agencieswp/v1/invoices?status=overdue&per_page=50" 
  -H "Authorization: Bearer awp_your_key_here"

[
  {
    "id": 42,
    "invoice_number": "INV-0042",
    "client_id": 7,
    "project_id": 11,
    "subscription_id": 0,
    "amount": 4000.00,
    "tax": 800.00,
    "discount": 0.00,
    "total": 4800.00,
    "paid_amount": 0.00,
    "status": "overdue",
    "payment_method": "",
    "due_date": "2026-09-30",
    "paid_date": null,
    "notes": "",
    "items": [
      { "description": "Website rebuild - phase 1", "qty": 1, "rate": 4000.00 }
    ],
    "created_at": "2026-09-01 10:14:02",
    "updated_at": "2026-10-01 00:00:11"
  }
]

A list is a plain JSON array. A single record is a plain JSON object. There is no wrapper envelope.

Fields

Each object returns an explicit list of fields. It is an allow-list, not a blocklist, so a column added to the database in a later release stays invisible to the API until it is deliberately published. Secrets are never on these lists.

The items field on invoices, recurring invoices and proposals is stored as JSON and returned as real JSON, not a string.

Creating records

Send JSON with Content-Type: application/json. Form-encoded bodies work too.

A client

curl -s -X POST https://your-site.com/wp-json/agencieswp/v1/clients 
  -H "Authorization: Bearer awp_your_key_here" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "Harbor Fintech",
    "email": "[email protected]",
    "company": "Harbor Fintech Ltd",
    "country": "GB",
    "tax_id": "GB123456789"
  }'

A successful create returns 201 with the new record, including the id the system assigned:

{ "id": 18, "unique_id": "CL100018", "name": "Harbor Fintech", "...": "..." }

A project

curl -s -X POST https://your-site.com/wp-json/agencieswp/v1/projects 
  -H "Authorization: Bearer awp_your_key_here" 
  -H "Content-Type: application/json" 
  -d '{
    "title": "Website rebuild",
    "client_id": 18,
    "status": "in_progress",
    "budget_type": "fixed",
    "budget": 12000,
    "due_date": "2027-02-28",
    "service_type": "Web design",
    "estimated_hours": 140
  }'

For an hourly project, send "budget_type": "hourly" with an hourly_rate. The budget then follows the hours logged against it.

A time log

curl -s -X POST https://your-site.com/wp-json/agencieswp/v1/time-logs 
  -H "Authorization: Bearer awp_your_key_here" 
  -H "Content-Type: application/json" 
  -d '{
    "project_id": 11,
    "log_date": "2026-10-28",
    "hours": 3.5,
    "billable": 1,
    "description": "Checkout flow QA"
  }'

Updating records

Use PATCH (or PUT) with only the fields you want changed. Anything you leave out keeps its current value.

curl -s -X PATCH https://your-site.com/wp-json/agencieswp/v1/invoices/42 
  -H "Authorization: Bearer awp_your_key_here" 
  -H "Content-Type: application/json" 
  -d '{ "status": "paid", "paid_amount": 4800.00, "paid_date": "2026-10-29" }'

It returns 200 with the updated record.

Summary figures

One call returns the headline numbers, which is handy for a dashboard tile without paging through every record.

curl -s https://your-site.com/wp-json/agencieswp/v1/stats 
  -H "Authorization: Bearer awp_your_key_here"

{
  "clients": { "total": 18 },
  "projects": {
    "total": 24, "pending": 2, "in_progress": 9, "completed": 13, "on_hold": 0
  },
  "invoices": {
    "total_count": 96,
    "total_invoiced": 184300.00,
    "total_paid": 171900.00,
    "total_due": 12400.00,
    "overdue_count": 2
  },
  "recurring": { "total": 7, "active": 6, "paused": 1, "mrr": 4180.00 },
  "currency": "USD"
}

mrr is monthly recurring revenue, with each plan’s amount normalised to a month. A quarterly plan counts as a third of its value, and a yearly one as a twelfth.

Errors

Errors come back in WordPress’s standard shape, with a matching HTTP status:

{
  "code": "insufficient_scope",
  "message": "This API key does not have the "write:invoices" permission.",
  "data": { "status": 403 }
}

Rate limit

The limit is 120 requests per minute per key. It is counted per key rather than per IP, so one integration cannot exhaust another’s allowance.

Going over returns 429. Wait for the next minute and continue. If you are importing in bulk, space the requests out, or page with a larger per_page instead of many small requests.

Integration tips

• Use one key per integration. If one has to be revoked, nothing else stops working.
• Grant the narrowest permissions that do the job. A key that only reads invoices cannot touch a client record, even if it is leaked.
• Store the key as a secret, not in a repository or a shared document.
• Use GET / as your health check. It confirms the key works and lists exactly what it can reach, which is faster than guessing at a 403.
• Nothing here deletes. If a record needs removing, do it in the WordPress admin.
• project_id is required on /milestones and /time-logs. Both are always read per project. There is no “all milestones” list.
• Client email addresses are unique. Creating a client with an address that already exists returns 400 duplicate_email rather than a second record, so an import that runs twice does not produce duplicates.

Support

Questions, or something not behaving as documented? Get in touch and I will help.