Download OpenAPI specification:Download
Welcome to the Payaca API docs.
The external API uses HTTP Basic Authentication with client credentials (Client ID and Client Secret).
API credentials can be created through the Payaca provider web application:
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 allow you to receive real-time notifications when events occur in your Payaca account.
(Under construction)
When a subscribed event occurs a POST request is made to the webhook URL with a JSON payload and signature from your provided secret.
All webhook payloads include an X-Payaca-Signature
header for verification,
containing an HMAC-SHA256 signature of the payload
X-Payaca-Signature: a2114d57b48eac7b4cde7f32c991906e42c79dc606e60c5093f02c3afc567f78
X-Payaca-Signature
header.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:
Update an existing Customer.
id required | string Example: 123 |
object or null Provide values for any custom fields the Account has configured for their Customers. The key should be the custom field identifier |
{- "customFields": {
- "property1": null,
- "property2": null
}
}
{- "customer": {
- "id": "123",
- "name": "Harper Property Management",
- "contacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful",
- "isPrimaryContact": true
}
], - "addresses": [
- {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
], - "isBillingAddress": true
}
], - "customFields": {
- "property1": null,
- "property2": null
}
}
}
Get an existing Customer.
id required | string Example: 123 |
{- "customer": {
- "id": "123",
- "name": "Harper Property Management",
- "contacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful",
- "isPrimaryContact": true
}
], - "addresses": [
- {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
], - "isBillingAddress": true
}
], - "customFields": {
- "property1": null,
- "property2": null
}
}
}
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.
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 |
{- "name": "Harper Property Management",
- "contacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful",
- "isPrimaryContact": true
}
], - "addresses": [
- {
- "address": {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom"
}, - "isBillingAddress": true,
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
]
}
], - "customFields": {
- "property1": null,
- "property2": null
}
}
{- "customer": {
- "id": "123",
- "name": "Harper Property Management",
- "contacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful",
- "isPrimaryContact": true
}
], - "addresses": [
- {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
], - "isBillingAddress": true
}
], - "customFields": {
- "property1": null,
- "property2": null
}
}
}
Project has been moved to a different pipeline stage.
x-payaca-signature required | string Signature of the webhook payload |
x-payaca-event required | string Value: "project.pipelineStageChanged" |
required | object (Project) |
{- "project": {
- "id": "123",
- "reference": "ABC123",
- "pipeline": {
- "title": "Install"
}, - "pipelineStage": {
- "title": "New Lead"
}, - "customer": {
- "id": "123",
- "name": "Harper Property Management",
- "contacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful",
- "isPrimaryContact": true
}
], - "addresses": [
- {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
], - "isBillingAddress": true
}
], - "customFields": {
- "property1": null,
- "property2": null
}
}, - "tags": [
- "string"
], - "assignedTo": {
- "fullName": "Johanna Employeeson",
- "email": "johanna.employeeson@payaca.com"
}, - "siteAddress": {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
]
}, - "customFields": {
- "property1": null,
- "property2": null
}, - "notes": [
- "string"
]
}
}
Creates a new project for the specified customer.
id required | string Example: 123 |
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, | |
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 |
{- "reference": "ABC123",
- "siteAddress": {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom"
}, - "tags": [
- "Priority",
- "Install"
], - "pipeline": {
- "title": "Install"
}, - "pipelineStage": {
- "title": "New lead"
}, - "assignTo": {
- "email": "johanna.employeeson@payaca.com"
}, - "notes": [
- "Design and estimate required"
], - "customFields": {
- "property1": null,
- "property2": null
}
}
{- "project": {
- "id": "123",
- "reference": "ABC123",
- "pipeline": {
- "title": "Install"
}, - "pipelineStage": {
- "title": "New Lead"
}, - "customer": {
- "id": "123",
- "name": "Harper Property Management",
- "contacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful",
- "isPrimaryContact": true
}
], - "addresses": [
- {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
], - "isBillingAddress": true
}
], - "customFields": {
- "property1": null,
- "property2": null
}
}, - "tags": [
- "string"
], - "assignedTo": {
- "fullName": "Johanna Employeeson",
- "email": "johanna.employeeson@payaca.com"
}, - "siteAddress": {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
]
}, - "customFields": {
- "property1": null,
- "property2": null
}, - "notes": [
- "string"
]
}
}
Updates an existing Project.
id required | string Example: 123 |
object or null Provide values for any custom fields the Account has configured for their Projects. The key should be the custom field identifier |
{- "customFields": {
- "property1": null,
- "property2": null
}
}
{- "project": {
- "id": "123",
- "reference": "ABC123",
- "pipeline": {
- "title": "Install"
}, - "pipelineStage": {
- "title": "New Lead"
}, - "customer": {
- "id": "123",
- "name": "Harper Property Management",
- "contacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful",
- "isPrimaryContact": true
}
], - "addresses": [
- {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
], - "isBillingAddress": true
}
], - "customFields": {
- "property1": null,
- "property2": null
}
}, - "tags": [
- "string"
], - "assignedTo": {
- "fullName": "Johanna Employeeson",
- "email": "johanna.employeeson@payaca.com"
}, - "siteAddress": {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
]
}, - "customFields": {
- "property1": null,
- "property2": null
}, - "notes": [
- "string"
]
}
}
Get an existing Project.
id required | string Example: 123 |
{- "project": {
- "id": "123",
- "reference": "ABC123",
- "pipeline": {
- "title": "Install"
}, - "pipelineStage": {
- "title": "New Lead"
}, - "customer": {
- "id": "123",
- "name": "Harper Property Management",
- "contacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful",
- "isPrimaryContact": true
}
], - "addresses": [
- {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
], - "isBillingAddress": true
}
], - "customFields": {
- "property1": null,
- "property2": null
}
}, - "tags": [
- "string"
], - "assignedTo": {
- "fullName": "Johanna Employeeson",
- "email": "johanna.employeeson@payaca.com"
}, - "siteAddress": {
- "line1": "123 Wallaby Street",
- "line2": "string",
- "city": "Bristol",
- "postcode": "BS1 AAA",
- "country": "United Kingdom",
- "regionallyUniqueIdentifier": "1234",
- "accessContacts": [
- {
- "fullName": "John Doe",
- "email": "john.doe@email.com",
- "phoneNumber": "+44 7777 777777",
- "description": "Very friendly and helpful"
}
]
}, - "customFields": {
- "property1": null,
- "property2": null
}, - "notes": [
- "string"
]
}
}
Get all custom fieldset definitions for the associated entity type
assocEntityType required | string Enum: "project" "customer" The type of entity to which custom fieldsets are associated |
{- "customFields": [
- {
- "identifier": "myCustomField",
- "label": "My custom field",
- "exampleValue": true,
- "schema": "{\"type\":[\"boolean\",\"null\"],\"$schema\":\"http://json-schema.org/draft/2020-12/schema\"}",
- "type": "fieldset",
- "children": [
- {
- "identifier": "myCustomField",
- "label": "My custom field",
- "exampleValue": true,
- "schema": "{\"type\":[\"boolean\",\"null\"],\"$schema\":\"http://json-schema.org/draft/2020-12/schema\"}",
- "type": "select",
- "options": [
- "Option 1",
- "Option 2",
- "Option 3"
]
}
]
}
]
}
Create for the associated entity type
assocEntityType required | string Enum: "project" "customer" The type of entity to which custom fieldsets are associated |
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 |
{- "identifier": "myCustomField",
- "label": "My custom field",
- "type": "fieldset",
- "children": [
- {
- "identifier": "myCustomField",
- "label": "My custom field",
- "type": "select",
- "options": [
- "Option 1",
- "Option 2",
- "Option 3"
]
}
]
}
{- "customFields": [
- {
- "identifier": "myCustomField",
- "label": "My custom field",
- "exampleValue": true,
- "schema": "{\"type\":[\"boolean\",\"null\"],\"$schema\":\"http://json-schema.org/draft/2020-12/schema\"}",
- "type": "fieldset",
- "children": [
- {
- "identifier": "myCustomField",
- "label": "My custom field",
- "exampleValue": true,
- "schema": "{\"type\":[\"boolean\",\"null\"],\"$schema\":\"http://json-schema.org/draft/2020-12/schema\"}",
- "type": "select",
- "options": [
- "Option 1",
- "Option 2",
- "Option 3"
]
}
]
}
]
}
Create within a specific fieldset
assocEntityType required | string Enum: "project" "customer" The type of entity to which custom fieldsets are associated |
fieldsetIdentifier required | string |
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 ] |
{- "identifier": "myCustomField",
- "label": "My custom field",
- "type": "select",
- "options": [
- "Option 1",
- "Option 2",
- "Option 3"
]
}
{- "identifier": "myCustomField",
- "label": "My custom field",
- "exampleValue": true,
- "schema": "{\"type\":[\"boolean\",\"null\"],\"$schema\":\"http://json-schema.org/draft/2020-12/schema\"}",
- "type": "fieldset",
- "children": [
- {
- "identifier": "myCustomField",
- "label": "My custom field",
- "exampleValue": true,
- "schema": "{\"type\":[\"boolean\",\"null\"],\"$schema\":\"http://json-schema.org/draft/2020-12/schema\"}",
- "type": "select",
- "options": [
- "Option 1",
- "Option 2",
- "Option 3"
]
}
]
}
Get all tax rates
offset | integer or null >= 0 Default: 0 |
limit | integer ( 0 .. 100 ] Default: 50 |
{- "taxRates": {
- "items": [
- {
- "id": "123",
- "label": "20% VAT",
- "isReverseCharge": false,
- "percentage": 20
}
], - "total": 0,
- "offset": 0,
- "limit": 0
}
}
Creates Notes against the specified Project.
id required | string Example: 123 |
[- "Design and estimate required"
]
{- "notes": [
- "string"
]
}
Creates a Proposal against the specified Project.
id required | string Example: 123 |
reference | string or null |
validForDays | integer or null |
required | Array of objects non-empty |
{- "reference": "ABC123",
- "validForDays": 30,
- "itemGroups": [
- {
- "description": "Group name",
- "items": {
- "required": [
- {
- "internalIdentifier": "BATT-ABC",
- "description": "4 KW solar panels 4.5 KW battery",
- "unitPrice": 1000000,
- "quantity": 1,
- "discount": {
- "percentage": 10,
- "description": "Valued customer discount"
}, - "taxRate": {
- "id": "ABC123"
}
}
], - "optional": [
- {
- "internalIdentifier": "BATT-ABC",
- "description": "4 KW solar panels 4.5 KW battery",
- "unitPrice": 1000000,
- "quantity": 1,
- "discount": {
- "percentage": 10,
- "description": "Valued customer discount"
}, - "taxRate": {
- "id": "ABC123"
}, - "selected": true
}
], - "multiChoice": [
- {
- "internalIdentifier": "BATT-ABC",
- "description": "4 KW solar panels 4.5 KW battery",
- "unitPrice": 1000000,
- "quantity": 1,
- "discount": {
- "percentage": 10,
- "description": "Valued customer discount"
}, - "taxRate": {
- "id": "ABC123"
}, - "selected": true
}
]
}
}
]
}
{- "proposal": {
- "reference": "ABC123",
- "type": "QUOTE",
- "validForDays": 30,
- "itemGroups": [
- {
- "description": "Group name",
- "items": {
- "required": [
- {
- "internalIdentifier": "BATT-ABC",
- "description": "4 KW solar panels 4.5 KW battery",
- "price": {
- "unitPrice": 10000,
- "cisDeductionRate": 20,
- "discount": {
- "percentage": 10,
- "description": "Valued customer discount"
}, - "taxRate": {
- "id": "123",
- "label": "20% VAT",
- "isReverseCharge": false,
- "percentage": 20
}
}, - "totals": {
- "subtotal": 10000,
- "tax": 2000,
- "discount": 1000,
- "cis": 2000,
- "total": 12000
}, - "quantity": 1,
- "selection": {
- "type": "OPTIONAL",
- "selected": true
}
}
], - "optional": [
- {
- "internalIdentifier": "BATT-ABC",
- "description": "4 KW solar panels 4.5 KW battery",
- "price": {
- "unitPrice": 10000,
- "cisDeductionRate": 20,
- "discount": {
- "percentage": 10,
- "description": "Valued customer discount"
}, - "taxRate": {
- "id": "123",
- "label": "20% VAT",
- "isReverseCharge": false,
- "percentage": 20
}
}, - "totals": {
- "subtotal": 10000,
- "tax": 2000,
- "discount": 1000,
- "cis": 2000,
- "total": 12000
}, - "quantity": 1,
- "selection": {
- "type": "OPTIONAL",
- "selected": true
}
}
], - "multiChoice": [
- {
- "internalIdentifier": "BATT-ABC",
- "description": "4 KW solar panels 4.5 KW battery",
- "price": {
- "unitPrice": 10000,
- "cisDeductionRate": 20,
- "discount": {
- "percentage": 10,
- "description": "Valued customer discount"
}, - "taxRate": {
- "id": "123",
- "label": "20% VAT",
- "isReverseCharge": false,
- "percentage": 20
}
}, - "totals": {
- "subtotal": 10000,
- "tax": 2000,
- "discount": 1000,
- "cis": 2000,
- "total": 12000
}, - "quantity": 1,
- "selection": {
- "type": "OPTIONAL",
- "selected": true
}
}
]
}
}
], - "totals": {
- "total": 12000
}
}
}