Methods
GET
Retrieve Single Correspondence
/backend/api/v1/correspondence/ID - fetch correspondence with specified ID.
- Set the
Acceptheader toapplication/pdfto request the PDF letter, rather than the JSON description.
List Correspondence
/backend/api/v1/correspondence/ - list all correspondence.
/backend/api/v1/customers/ID/correspondence/ - list correspondence belonging to customer with specified ID.
Additional Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
correspondenceType |
string | No | Show only correspondence of the named type |
delivered |
flag | No | Show only delivered correspondence |
undelivered |
flag | No | Show only undelivered correspondence |
minDate |
date | No | Only show correspondence dated on or after |
maxDate |
date | No | Only show correspondence dated on or before |
Note: The delivered and undelivered filters are mutually exclusive. If both are present, no results are returned.
Note: The min/maxDate filters use the correspondence date, and the standard createdSince filter uses the time the record was created in the platform. These will often be the same, but this is not guaranteed.
POST
/backend/api/v1/customers/ID/correspondence/ - add new correspondence to the specified customer. The newly-added correspondence will be returned.
PATCH
/backend/api/v1/correspondence/ID - update correspondence with specified ID. The modified correspondence will be returned.
DELETE
/backend/api/v1/correspondence/ID - delete correspondence with specified ID.
Actions
Available Actions
Email correspondence to the customer or other recipients. The correspondence must be ready before it can be emailed.
Parameters:
email(optional) - An array of email addresses to send the correspondence to. If not provided, the correspondence is sent to the email addresses on the customer record and appropriate contacts. Addresses can also be passed as comma-separated strings.attachments(optional) - Extra documents to attach. An array of attachment names.
Example:
curl -X POST https://example.com/backend/api/v1/correspondence/123?action=email \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"email": ["[email protected]", "[email protected]"]
}'
deliver
Mark correspondence as delivered manually. The correspondence must be ready.
Parameters: No required parameters.
Example:
curl -X POST https://example.com/backend/api/v1/correspondence/123?action=deliver \
-H "Authorization: Bearer YOUR_API_TOKEN"
Response Format
Actions return a JSON response:
emailreturns{"success": true, "message": "..."}on successdeliverreturns the updated correspondence object
Error Handling
If an action fails, the API returns an appropriate HTTP status code with error details:
{
"error": "Invalid Action",
"error_code": 400502,
"hint": "The action was not performed"
}
Common error codes:
400501- Action not recognised400502- Action failed403xxx- Permission denied404107- Correspondence file not available404108- Correspondence has no attachment500603- Email sending failed
Fields
| Field | Name | Type | Description |
|---|---|---|---|
| correspondenceNumber | Correspondence Number | Text | Sequential correspondence number for this customer, automatically assigned if left blank |
| correspondenceDate | Correspondence Date | Date | Date when this correspondence was created |
| status | Status | Preset Value(s) | Array of status names currently active for this correspondence |
| correspondenceType | Correspondence Type | Preset Value | Type of correspondence which determines the content sections and formatting |
| id | Correspondence ID | Text | The unique identifier for this correspondence record |