Correspondence

Methods

GET

Retrieve Single Correspondence

/backend/api/v1/correspondence/ID - fetch correspondence with specified ID.

• Set the Accept header to application/pdf to 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

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

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": ["accounts@example.com", "billing@example.com"]
  }'

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:

• email returns {"success": true, "message": "..."} on success
• deliver returns 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 recognised
• 400502 - Action failed
• 403xxx - Permission denied
• 404107 - Correspondence file not available
• 404108 - Correspondence has no attachment
• 500603 - Email sending failed

Fields