Payaca API (1.0.0)

Download OpenAPI specification:Download

Tech Team: tech@payaca.com License: Proprietary

Welcome to the Payaca API docs.

Authentication

The external API uses HTTP Basic Authentication with client credentials (Client ID and Client Secret).

Creating API Credentials

API credentials can be created through the Payaca provider web application:

  1. Navigate to My Company → Integrations
  2. Click "Create API key"
  3. Provide a name for the credentials
  4. Record the generated Client ID and Client Secret immediately - the secret cannot be retrieved again

Making Authenticated Requests

Include your credentials in the Authorization header using HTTP Basic Authentication:

curl -X GET https://api.payaca.com/v1/customers \
  -u "your-client-id:your-client-secret"

Or encode the credentials manually:

# Base64 encode "client-id:client-secret"
AUTH_HEADER=$(echo -n "your-client-id:your-client-secret" | base64)

curl -X GET https://api.payaca.com/v1/customers \
  -H "Authorization: Basic $AUTH_HEADER"

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your Payaca account.

Registering a Webhook subscriber

(Under construction)

Webhook Delivery

When a subscribed event occurs a POST request is made to the webhook URL with a JSON payload and signature from your provided secret.

Webhook Signature Verification

All webhook payloads include an X-Payaca-Signature header for verification, containing an HMAC-SHA256 signature of the payload

X-Payaca-Signature: a2114d57b48eac7b4cde7f32c991906e42c79dc606e60c5093f02c3afc567f78

Verification Process

  1. Compute Signature: Create HMAC-SHA256 hex digest of the entire request body, using your webhook secret
  2. Compare: Use timing-safe comparison to verify your signature matches the X-Payaca-Signature header.

Retry Logic

If you respond with HTTP 2XX or 4XX, we will not attempt to redeliver a webhook.

We will retry with exponential backoff in the following circumstances:

  • HTTP 5xx response,
  • Network errors
  • Response timeouts (up to 3 seconds)

Customers

Customers: Update

Update an existing Customer.

Authorizations:
basicAuth
path Parameters
id
required
string
Example: 123
Request Body schema: application/json
object or null

Provide values for any custom fields the Account has configured for their Customers. The key should be the custom field identifier

Responses

Request samples

Content type
application/json
{
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Customers: Get

Get an existing Customer.

Authorizations:
basicAuth
path Parameters
id
required
string
Example: 123

Responses

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Customers: Create or update

Creates a new Customer, or if any Customer with an email exists, adds to that one instead. If multiple Customers are found, the earliest created one is used.

Authorizations:
basicAuth
Request Body schema: application/json
name
string or null
required
Array of objects non-empty
Array of objects or null
object or null

Provide values for any custom fields the Account has configured for their Customers. The key should be the custom field identifier

Responses

Request samples

Content type
application/json
{
  • "name": "Harper Property Management",
  • "contacts": [
    ],
  • "addresses": [
    ],
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "customer": {
    }
}

Projects

Project Pipeline Stage Changed Webhook

Project has been moved to a different pipeline stage.

Authorizations:
basicAuth
header Parameters
x-payaca-signature
required
string

Signature of the webhook payload

x-payaca-event
required
string
Value: "project.pipelineStageChanged"
Request Body schema: application/json
required
object (Project)

Responses

Request samples

Content type
application/json
{
  • "project": {
    }
}

Projects: Create

Creates a new project for the specified customer.

Authorizations:
basicAuth
path Parameters
id
required
string
Example: 123
Request Body schema: application/json
reference
string or null
Structured (object) or String (string) or null
tags
Array of strings or null/^((\u00a9|\u00ae|[\u2000-\u3300]|\ud83c[\ud0...
By title (object) or By id (object) or null

The pipeline to create the Project within

By title (object) or By id (object) or null

The stage of the pipeline to start the Project in. If set, pipeline must also be provided

object or null

The email address of the Payaca user to assign the Project to

notes
Array of strings or null
object or null

Provide values for any custom fields the Account has configured for their Projects. The key should be the custom field identifier

Responses

Request samples

Content type
application/json
{
  • "reference": "ABC123",
  • "siteAddress": {
    },
  • "tags": [
    ],
  • "pipeline": {
    },
  • "pipelineStage": {
    },
  • "assignTo": {
    },
  • "notes": [
    ],
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "project": {
    }
}

Projects: Update

Updates an existing Project.

Authorizations:
basicAuth
path Parameters
id
required
string
Example: 123
Request Body schema: application/json
object or null

Provide values for any custom fields the Account has configured for their Projects. The key should be the custom field identifier

Responses

Request samples

Content type
application/json
{
  • "customFields": {
    }
}

Response samples

Content type
application/json
{
  • "project": {
    }
}

Projects: Get

Get an existing Project.

Authorizations:
basicAuth
path Parameters
id
required
string
Example: 123

Responses

Response samples

Content type
application/json
{
  • "project": {
    }
}

Custom Fieldsets

Custom Fieldsets: Get all for the associated entity type

Get all custom fieldset definitions for the associated entity type

Authorizations:
basicAuth
path Parameters
assocEntityType
required
string
Enum: "project" "customer"

The type of entity to which custom fieldsets are associated

Responses

Response samples

Content type
application/json
{
  • "customFields": [
    ]
}

Custom Fieldsets: Create for the associated entity type

Create for the associated entity type

Authorizations:
basicAuth
path Parameters
assocEntityType
required
string
Enum: "project" "customer"

The type of entity to which custom fieldsets are associated

Request Body schema: application/json
identifier
string or null <= 255 characters ^[a-zA-Z0-9-]+$

A unique identifier for the custom field - this will be auto generated if none provided

label
required
string <= 1023 characters

A readable field label

type
required
string
Value: "fieldset"
required
Array of Select field (object) or Simple field (object) [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "identifier": "myCustomField",
  • "label": "My custom field",
  • "type": "fieldset",
  • "children": [
    ]
}

Response samples

Content type
application/json
{
  • "customFields": [
    ]
}

Custom Fieldsets: Create within a specific fieldset

Create within a specific fieldset

Authorizations:
basicAuth
path Parameters
assocEntityType
required
string
Enum: "project" "customer"

The type of entity to which custom fieldsets are associated

fieldsetIdentifier
required
string
Request Body schema: application/json
Any of
identifier
string or null <= 255 characters ^[a-zA-Z0-9-]+$

A unique identifier for the custom field - this will be auto generated if none provided

label
required
string <= 1023 characters

A readable field label

type
required
string
Value: "select"
options
required
Array of strings [ 1 .. 20 ] items [ items <= 255 characters ]

Responses

Request samples

Content type
application/json
Example
{
  • "identifier": "myCustomField",
  • "label": "My custom field",
  • "type": "select",
  • "options": [
    ]
}

Response samples

Content type
application/json
{
  • "identifier": "myCustomField",
  • "label": "My custom field",
  • "exampleValue": true,
  • "schema": "{\"type\":[\"boolean\",\"null\"],\"$schema\":\"http://json-schema.org/draft/2020-12/schema\"}",
  • "type": "fieldset",
  • "children": [
    ]
}

Tax Rates

Tax Rates: Get all

Get all tax rates

Authorizations:
basicAuth
query Parameters
offset
integer or null >= 0
Default: 0
limit
integer ( 0 .. 100 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "taxRates": {
    }
}

Project Notes

Project Notes: Create

Creates Notes against the specified Project.

Authorizations:
basicAuth
path Parameters
id
required
string
Example: 123
Request Body schema: application/json
Array ([ 1 .. 10 ] items)
string

Responses

Request samples

Content type
application/json
[
  • "Design and estimate required"
]

Response samples

Content type
application/json
{
  • "notes": [
    ]
}

Project Proposals

Project Proposal: Create

Creates a Proposal against the specified Project.

Authorizations:
basicAuth
path Parameters
id
required
string
Example: 123
Request Body schema: application/json
reference
string or null
validForDays
integer or null
required
Array of objects non-empty

Responses

Request samples

Content type
application/json
{
  • "reference": "ABC123",
  • "validForDays": 30,
  • "itemGroups": [
    ]
}

Response samples

Content type
application/json
{
  • "proposal": {
    }
}